Ikemen GO Documentation

You can build the engine and an installable APK using Docker without needing Android Studio. This requires Docker (Desktop on Windows/macOS, or Engine on Linux).

Option A: Helper Script

Run the one-liner from the repository root:

./build/build_android.sh

Option B: Docker Compose

docker compose -f build/docker/android/docker-compose.yml build
docker compose -f build/docker/android/docker-compose.yml run --rm android-build

Outputs

Successful builds populate:

• bin/ikemen-go.apk (The APK)
• bin/libmain.so and bin/libmain.h (Engine shared library + header)
• lib/*.so (Android runtime dependencies: SDL2, FFmpeg, libxmp, etc.)
• build/android-apk/ikemen-droid (The cloned Android wrapper project)

Configuration

To skip APK packaging and only build the shared library and dependencies:

BUILD_ANDROID_APK=0 docker compose -f build/docker/android/docker-compose.yml run --rm android-build

To customize the wrapper (package name, icons, etc.), fork the ikemen-droid project and provide the URL and reference via environment variables:

APP_VERSION=my-build \\ 
ANDROID_APK_REPO=https://github.com/YourUser/ikemen-droid.git \\ 
ANDROID_APK_REF=main \\ 
docker compose -f build/docker/android/docker-compose.yml run --rm android-build

1. Install Dependencies (Debian/Ubuntu)

sudo apt update && sudo apt install -y \
  golang-go git pkg-config make nasm yasm build-essential \
  libxmp-dev libsdl2-dev

2. Build x86-64 (Ikemen_GO_Linux)

git clone https://github.com/ikemen-engine/Ikemen-GO.git
cd Ikemen-GO
./build/build.sh Linux
# or
make Ikemen_GO_Linux

3. Build ARM64 on ARM Host (Ikemen_GO_LinuxARM)

./build/build.sh LinuxARM
# or
make Ikemen_GO_LinuxARM

4. Run and Troubleshooting

Run the binary:

./Ikemen_GO_Linux

If you encounter GL driver issues, use the MESA fallback:

MESA_GL_VERSION_OVERRIDE=2.1 ./Ikemen_GO_Linux

5. Use System FFmpeg (Optional)

Install the required dev packages (ffmpeg, libavcodec-dev, libavformat-dev, libavutil-dev, libswscale-dev, libswresample-dev, libavfilter-dev) and run:

BUILD_FFMPEG=no ./build/build.sh Linux

To build on Windows, use MSYS2 with the MINGW64 environment. You must install several development packages via pacman to provide pkg-config support for FFmpeg, libxmp, and SDL2.

1. Install Dependencies

Open MSYS2 MINGW64 and run:

pacman -Syu --noconfirm
pacman -S --noconfirm \
  git make diffutils mingw-w64-x86_64-pkg-config \
  mingw-w64-x86_64-go mingw-w64-x86_64-toolchain \
  mingw-w64-x86_64-nasm mingw-w64-x86_64-yasm \
  mingw-w64-x86_64-tools-git mingw-w64-x86_64-libxmp \
  mingw-w64-x86_64-SDL2

2. Build 64-bit (Ikemen_GO.exe)

git clone https://github.com/ikemen-engine/Ikemen-GO.git
cd Ikemen-GO
./build/build.sh Win64
# or
make Ikemen_GO.exe

3. Build 32-bit (Ikemen_GO_x86.exe)

Requires additional 32-bit MinGW cross tools:

pacman -S --noconfirm mingw-w64-i686-toolchain mingw-w64-i686-pkg-config mingw-w64-i686-nasm mingw-w64-i686-yasm mingw-w64-i686-libxmp mingw-w64-i686-SDL2

./build/build.sh Win32
# or
make Ikemen_GO_x86.exe

4. Use System FFmpeg (Optional)

If you have mingw-w64-x86_64-ffmpeg installed and want to avoid the auto-build:

BUILD_FFMPEG=no ./build/build.sh Win64

The Synchronize() method on NetConnection ensures that both players are running with identical game parameters to prevent desyncs.

Synchronization Workflow

1. Config Exchange: Uses sys.synchronizeNetplayConfig to exchange SyncSetting lists (covering strict and host scopes).
2. Seed Sync: The host generates a random seed and sends it to the guest via writeI32. Both players then call Srand(seed).
3. Pre-match Time Sync: The host's preMatchTime is sent to the guest to ensure consistent timing.
4. Time Verification: The host writes its current time and the guest verifies it matches. If they differ, a Synchronization error is returned.
5. Input Buffer Reset: Local and remote input buffers are reset to the current synchronized time.
6. Input Streaming: Starts background goroutines to continuously write local inputs to the network and read remote inputs into the buffer.

Netplay sessions use a mechanism called a Session Config Override to ensure all participants use identical synchronization settings, regardless of their local configuration.

How it works:

1. Handshake: During synchronizeNetplayConfig, the host and guest exchange SyncHandshake payloads containing SyncVersion, Strict settings, Host settings, and a ContentFingerprint.
2. Validation: The engine validates that the settings are compatible and that the content fingerprints match.
3. Override: If valid, beginSessionOverride is called. This temporarily replaces the local configuration (s.cfg) with the settings agreed upon during the handshake. This ensures that even if a user has different local settings, the active netplay session remains deterministic.
4. Restoration: Once the session ends, endSyncSessionOverride is called to restore the original local configuration.

Replay Sessions

Replays also use this mechanism. When starting a replay via beginReplaySession, the engine validates the ReplayHeader against local settings and applies an override to match the settings used when the replay was originally recorded.