extension

OCAP Recorder (Go)

About

A Go implementation of an ArmA 3 native extension that records gameplay to PostgreSQL (with SQLite fallback). Captures unit positions, combat events, markers, and more for mission replay and analytics.

Architecture

Overview

ArmA 3 Game
    ↓ callExtension("ocap_recorder", [":COMMAND:", args])
RVExtensionArgs() [CGo boundary]
    ↓
Dispatcher.Dispatch(Event)
    ↓
    ├─ [Buffered] → Channel → Goroutine → Handler
    └─ [Sync]     → Handler directly
           ↓
Handler (parse args, validate, create model)
    ↓
    ├─ Storage Backend (if configured)
    └─ Queue (traditional) → batch insert every 2s
           ↓
DB Writer Loop
    ↓
PostgreSQL / SQLite

DLL Entry Points

The extension exposes CGo-exported functions that ArmA 3 calls:

Event Dispatcher

The dispatcher routes commands to handlers with optional buffering:

• Sync handlers: Execute immediately (entity creation)
• Buffered handlers: Queue events in channels for async processing (high-volume state updates)
• Metrics: OpenTelemetry integration for queue sizes, events processed/dropped

Project Structure

cmd/ocap_recorder/main.go    Entry point, initialization, lifecycle commands
pkg/a3interface/             CGo exports (RVExtension*)
internal/
├── dispatcher/              Event routing with async buffering
├── worker/                  Handler registration and DB writer loop
├── handlers/                Business logic for parsing and validation
├── queue/                   Thread-safe queues for batch writes
├── cache/                   Entity lookup caching (ObjectID → model)
├── model/                   GORM database models
├── storage/                 Optional alternative storage backend
└── geo/                     Coordinate/geometry utilities

Design Principles

1. Low latency: Async buffered handlers don't block ArmA's game loop
2. High throughput: Batch writes every 2 seconds instead of per-event
3. Entity caching: Sync entity creation → cache → async state updates use cached FK
4. Graceful fallback: PostgreSQL → SQLite if connection fails
5. Observability: OpenTelemetry metrics and structured logging (slog)

Building

Requires Docker with Linux containers.

Windows DLL

docker pull x1unix/go-mingw:1.24

docker run --rm -v ${PWD}:/go/work -w /go/work x1unix/go-mingw:1.24 \
  go build -buildvcs=false -o dist/ocap_recorder_x64.dll -buildmode=c-shared ./cmd/ocap_recorder

Linux .so

docker run --rm -v ${PWD}:/go/work -w /go/work golang:1.24-bullseye \
  go build -buildvcs=false -o dist/ocap_recorder_x64.so -buildmode=c-shared ./cmd/ocap_recorder

Uses Debian Bullseye (glibc 2.31) for broad compatibility with Linux game servers.

Configuration

Copy ocap_recorder.cfg.json.example to ocap_recorder.cfg.json alongside the DLL and edit as needed.

Supported Commands

Entity Commands

Combat Commands

General Commands

Marker Commands

ACE3 Integration

Lifecycle Commands