Skip to content

README.adoc

Latest commit

 

History

History
288 lines (214 loc) · 7.53 KB

README.adoc

File metadata and controls

288 lines (214 loc) · 7.53 KB

IDApTIK

Overview

IDApTIK is an educational network simulation game combining platformer infiltration with realistic hacking mechanics. Players work together in asymmetric co-op roles — one infiltrates physically while the other hacks remotely — to breach corporate networks, exfiltrate data, and escape undetected.

Originally created by Joshua B. Jewell, developed under hyperpolymath.

Architecture

Layer Technology

Frontend

ReScript 12 + PixiJS 8 (2D WebGL)

Game VM

Reversible VM — 23 instructions, ReScript core + Zig WASM backend (41M ops/sec)

Sync Server

Elixir/Phoenix (WebSocket channels, ETS sessions)

Modding Studio

Tauri 2 (Rust backend, PixiJS editor, procedural WorldGen)

ABI

Idris2 (15 modules, dependent-type proofs)

FFI

Zig (12 exports, C-ABI compatible)

Build

Deno + Vite + just

Containers

Chainguard base images, Podman

Components

Component Description Location

Main Game

ReScript/PixiJS game client — combat, stealth, devices, narrative

src/app/

Game Engine

Core engine: navigation, audio, resize, screen lifecycle

src/engine/

Bindings

PixiJS, @pixi/sound, motion FFI bindings

src/bindings/

Reversible VM

23-instruction VM with undo/redo, snapshots, memory-safe execution

vm/

WASM VM

Zig implementation of the VM targeting WebAssembly (41M ops/sec)

vm/wasm/

Shared

Cross-component types, utilities, 640+ tests across 20+ suites

shared/

Sync Server

Elixir/Phoenix multiplayer — channels, sessions, co-op broadcast

sync-server/

Universal Modding Studio

Tauri 2 desktop app — WorldGen (8 presets), PixiJS level editor

idaptik-ums/

Developer Portal

Developer documentation and tools

idaptik-developers/

Escape Hatch

Rust TUI (ratatui) — emergency game state inspector

idaptik-developers/src/escape-hatch/

DLC

Downloadable puzzle packs

dlc/

Containers

Chainguard-based Containerfiles for game and sync server

containers/

Tools

Balance analyser (Julia Monte Carlo simulation)

tools/

Locales

i18n JSON files via polyglot-i18n (5 languages)

locales/

Contractiles

Contractile CLI recipes (must/trust/dust/lust/k9)

contractiles/

Quick Start

Prerequisites

  • Deno — runtime and package manager

  • Elixir — for multiplayer sync server (optional for single-player)

  • just — task runner

Single-Player (Game Only)

./start-game-only.sh

Starts the Vite dev server on port 8080. Open http://localhost:8080.

Full Development Environment

deno task dev

Or with multiplayer:

./start-dev.sh

Starts the Elixir sync server on port 4030 and Vite on port 8080.

Testing

Run the full test suite (640+ tests across 20+ suites):

just test

Individual suites:

just test-shared    # Shared library tests
just test-vm        # VM tests
just test-deno      # Deno-specific tests (coprocessor, kernel, port-names)

Balance Analysis

Run Monte Carlo simulations to validate game balance:

just balance

Uses the Julia balance analyser in tools/balance-analyser.jl.

Universal Modding Studio (UMS)

The UMS is a Tauri 2 desktop application for level design and modding.

  • WorldGen: Procedural world generation with 8 presets

  • PixiJS Editor: Visual level editor

  • Idris2 ABI: 15 formally verified interface modules in idaptik-ums/src/abi/

  • Zig FFI: 12 C-ABI exports in idaptik-ums/ffi/zig/

Multiplayer

Asymmetric co-op multiplayer over Phoenix Channels (WebSocket):

  • Real-time session management via ETS

  • Co-op event broadcasting

  • VM network synchronisation across players

  • Asymmetric roles: hacker + infiltrator

Configuration lives in sync-server/config/. Key environment variables:

  • SECRET_KEY_BASE — Phoenix secret key (auto-generated in dev)

  • PHX_HOST — hostname (default: localhost)

  • PORT — server port (default: 4030)

Internationalisation

Five languages supported via polyglot-i18n:

File Language

locales/en.json

English

locales/de.json

German

locales/es.json

Spanish

locales/fr.json

French

locales/ja.json

Japanese

PanLL Integration

28 game development panels are available through the PanLL panel framework, covering level design, VM debugging, balance tuning, network topology editing, and more.

Directory Structure

idaptik/
├── src/
│   ├── app/              # Main game (ReScript, PixiJS)
│   ├── engine/           # Game engine core
│   └── bindings/         # PixiJS/sound FFI bindings
├── vm/
│   ├── src/              # ReScript VM core
│   ├── tests/            # VM tests
│   ├── benchmarks/       # Performance benchmarks
│   └── wasm/             # Zig WASM VM (41M ops/sec)
├── shared/
│   ├── src/              # Cross-component types and utilities
│   ├── lib/              # Compiled output
│   └── tests/            # 640+ tests across 20+ suites
├── sync-server/          # Elixir/Phoenix multiplayer
├── idaptik-ums/          # Universal Modding Studio (Tauri 2)
│   ├── src/abi/          # Idris2 ABI (15 modules)
│   ├── ffi/zig/          # Zig FFI (12 exports)
│   ├── src/              # Editor UI + WorldGen + PixiJS
│   └── src-tauri/        # Rust backend
├── idaptik-developers/   # Developer portal
│   ├── src/escape-hatch/ # Rust TUI (ratatui)
│   └── docs/             # White papers
├── dlc/                  # DLC puzzle packs
├── containers/           # Containerfiles (Chainguard)
├── tools/                # Balance analyser (Julia)
├── locales/              # i18n JSON files (5 languages)
├── contractiles/         # Contractile CLI recipes
├── .machine_readable/    # .machine_readable/6a2/STATE.a2ml, .machine_readable/6a2/META.a2ml, .machine_readable/6a2/ECOSYSTEM.a2ml
├── .well-known/          # hypatia.toml
└── .github/workflows/    # CI (16 workflows)

Building for Production

# Build the game
deno task build
# Output in dist/ — serve with any static file server

# Build Elixir sync server release
cd sync-server
MIX_ENV=prod mix release
# Output in _build/prod/rel/

License

AGPL-3.0-or-later (Palimpsest License). See LICENSE for the full text.