engine

README

goxpyriment

goxpyriment is a high-level Go framework for building behavioral and psychological experiments.

It relies on the libsdl library through the go-sdl3 bindings. Its API is largely inspired from expyriment.org ; see Krause, F., & Lindemann, O. (2014). Expyriment: A Python library for cognitive and neuroscientific experiments. Behavior Research Methods, 46(2), 416-428. https://doi.org/10.3758/s13428-013-0390-6.

It can be used to "vibe-code" psychology experiments.

Here is how to proceed:

1. Install Go on your machine (see https://go.dev/doc/install)

2. Clone this repository (git clone https://github.com/chrplr/goxpyriment.git or download ZIP)

3. Fire your favorite AI coding agent (gemini-cli, claude, cursor...) inside goxpyriment folder, then ask it to program your experiment, describing the stimuli, the desing, ... in plain language, in Go using the current library.

4. Once the code is created, say in myexp/main.go, you can test it by running the following command in the terminal:

   cd myexp
   go run main.go
   

5. Lastly, if you want, you can distribute an executable to your colleagues, creating installers for Windows, MacOS and Linux (see an example at https://github.com/chrplr/retinotopy-go)

**NOTE: This software in an alpha version, a proof of concept that without any doubt has some bugs. If you want to try and use it, I recommand you to clone this repository. Check out expe3000-go for a less ambitious but efficient, no-code, experiment generator **

Features

• Experimental Design: Easily define Experiments, Blocks, and Trials with support for factors and randomization.
• Rich Stimuli Library:
  • Visual: Text (lines and boxes), shapes (rectangles, circles), images, fixation crosses, and Gabor patches.
  • Audio: Playback of WAV files and synthetic tones.
• Hardware Acceleration: Seamless integration with SDL3 for smooth, high-performance stimulus presentation.
• Input Handling: Simplified interfaces for Keyboard and Mouse events.
• Data Collection: Automatic logging of trial data to .xpd files for later analysis.
• Timing: High-precision timing utilities for stimulus duration and reaction time measurement.

Prerequisites

• Go: Version 1.25 or higher.
• SDL3: The SDL3 development libraries must be installed on your system.
  • On Linux: Use your package manager (e.g., sudo apt install libsdl3-dev).
  • On macOS/Windows: Follow the official SDL3 installation guides.

Installation

go get github.com/chrplr/goxpyriment

Quick Start

Here is the code of a simple "Hello World" experiment.

package main

import (
	_ "embed"   # to embed stimuli files, font, ... inside the executable
	"flag"
	"log"

	"github.com/chrplr/goxpyriment/control"
	"github.com/chrplr/goxpyriment/stimuli"
)

//go:embed assets/bonjour.wav
var bonjourWav []byte

func main() {
	fullscreen := flag.Bool("F", false, "Launch in fullscreen display mode")
	flag.Parse()

	exp := control.NewExperiment(
		"My First Go Experiment",
		1368, 1024, *fullscreen,
		control.Black,  // background color
		control.White,  // foreground (text) color
		32,             // default font size in points
	)
	if err := exp.Initialize(); err != nil {
		log.Fatalf("failed to initialize experiment: %v", err)
	}
	defer exp.End()

	greetings := stimuli.NewTextBox("Hello World !", 600, sdl.FPoint{X: 0, Y: 100}, control.DefaultTextColor)
	instr := stimuli.NewTextBox("Press any key to start the experiment", 600, sdl.FPoint{X: 0, Y: 100}, control.DefaultTextColor)
	finish := stimuli.NewTextBox("Experiment Finished!\n Press any key to exit.", 600, sdl.FPoint{X: 0, Y: 100}, control.DefaultTextColor)

	sound := stimuli.NewSoundFromMemory(bonjourWav)
	if err := sound.PreloadDevice(exp.AudioDevice); err != nil {
		log.Printf("Warning: failed to load sound: %v", err)
	}

	 stimuli.PlayPing(exp.AudioDevice)

	 instr.Present(exp.Screen, true, true)
	 exp.Keyboard.Wait()

	 sound.Play()
	 greetings.Present(exp.Screen, true, true)
	 exp.Keyboard.Wait()

	 finish.Present(exp.Screen, true, true)
	 exp.Keyboard.Wait()
}

Assuming Go is installed on your computer (https://go.dev/doc/install), you can generate an executable program from the above code:

# Note: main.go and the assets are in `examples/hello_word` in this repository 
cp -r examples/hello_world  ~/tmp
cd ~/tmp
go mod init hello
go mod tidy   # This will download all the necessary modules. Will take some time the first time.
go build . -o hello_goxpy

You can then execute hello_goxpy from any location on your computer. Moreover, as cross-compiling is trivial in Go, one can easily generate apps for Windows, MacOS and Linux, on intel or arm architecture, from any computer.

Project Structure

• control/: Experiment lifecycle and state management (window, fonts, colors).
• design/: Tools for building the experimental structure (Trials, Blocks).
• stimuli/: A comprehensive library of visual and auditory stimuli.
• io/: Screen, Keyboard, and Mouse handling.
• clock/: Timing utilities.
• geometry/: Geometry utilities.
• examples/: Ready-to-run examples (Stroop task, Lexical Decision, etc.).

Building and Running Examples

To run a specific example, just execute go run on its main.go source file:

go run examples/parity_decision/main.go

Alternatively, you can build and run the binary:

cd examples/parity_decision
go build .
./parity_decision

Note: Most examples support a -d flag for windowed development mode.

You can build all examples at once using the provided script:

cd examples
./build.sh

License

This project is licensed under the GNU Public License v3 - see the LICENSE file for details.

Christophe Pallier, 2026

Documentation

Index

• type FrameIndex
• type GVHeader
• type VideoResource
  • func (v *VideoResource) Destroy()
  • func (v *VideoResource) UpdateFrame(targetFrame int) bool

Types

type FrameIndex

type FrameIndex struct {
	Address uint64
	Size    uint64
}

type GVHeader

type GVHeader struct {
	Width      uint32
	Height     uint32
	FrameCount uint32
	FPS        float32
	Format     uint32 // 0 = Raw RGBA
	FrameBytes uint32 // Total uncompressed bytes per frame
}

GVHeader matches the binary format produced by images2gv

type VideoResource

type VideoResource struct {
	Header    GVHeader
	File      *os.File
	Indices   []FrameIndex
	Texture   *sdl.Texture
	RGBA      []byte
	FPS       float64
	W, H      float32
	LastFrame int // Index of last decoded frame
}

func (*VideoResource) Destroy

func (v *VideoResource) Destroy()

func (*VideoResource) UpdateFrame

func (v *VideoResource) UpdateFrame(targetFrame int) bool