Language: English (base) | Korean

This English README is the base version. Keep README.ko.md as the Korean translation of this document, and update the English version first when product direction or repository structure changes.

LUX = Linalab Unity X

LUX is a local-first server/MCP evidence-gated automation control plane for game projects. It connects AI coding tools to engine projects through installed bridge adapters, records runtime truth under .lux/, and exposes verified project state through CLI, HTTP/WebSocket, and MCP surfaces.

Unity is the primary public-beta verified engine path. Godot and Three.js support must stay inside explicit capability tiers so planned, partial, or adapter-only behavior is not presented as completed product behavior.

LUX is not a Unity package and not a target game project. It is an independent local server and CLI that sits between AI assistants and engine projects.

The core problem is that AI coding tools understand source files but usually cannot see the current engine state: selected objects, PlayMode, compile logs, scene hierarchy, coordinates, camera state, UI layout, screenshots, and run results. LUX makes those surfaces observable and repeatable before an agent claims progress.

The basic flow is:

1. Install an engine bridge adapter into the target project.
2. Run the Rust gateway locally.
3. Let AI tools use CLI, HTTP/WebSocket, or MCP commands.
4. Record runtime truth and evidence under .lux/.
5. Verify behavior through engine status, compile/test/run output, screenshots, logs, or structured run evidence.

LUX moves in a fixed loop: capture local truth, decide from evidence, act through the gateway, verify through the engine or .lux/, then write the result back as durable context. The loop is intentionally slower than a direct code edit because it keeps AI agents from claiming progress from stale assumptions.

1. Observe - read .lux/, project files, engine capability state, Unity bridge status, logs, scene hierarchy, screenshots, and recent run evidence.
2. Route - choose the verified surface for the engine and task. Unity can use the full bridge-backed path; Godot and Three.js must stay inside their declared maturity tier.
3. Act - run CLI, HTTP/WebSocket, MCP, or bridge commands through the Rust gateway instead of mutating runtime state from side channels.
4. Verify - capture compile/test/run/status evidence before presenting behavior as done.
5. Project - expose the proven state back through README, docs/, skills, CLI output, and .lux/ summaries without turning planned capabilities into completed claims.

This rhythm makes LUX a local-first control plane, not a GUI product, remote streaming stack, or target game repository.

Bridge sources are ordinary files in this repository. Do not initialize bridge/ as a git dependency, and do not point it at lux-bridge or any other remote bridge repository. If bridge behavior changes, the source change should be visible in this repo beside the gateway code that installs or talks to it.

Engine support uses capability routing, not equal verification maturity. Unity is the primary verified path. Godot and Three.js entries expose only the commands and evidence levels that are actually supported.

See docs/godot-support.md for Godot-specific capability status.

flowchart LR
    subgraph AI["AI assistants"]
        Claude["Claude Code"]
        OpenCode["OpenCode"]
        Codex["OpenAI Codex"]
        Other["Other AI clients"]
    end

    subgraph Local["Local machine - localhost only"]
        subgraph Gateway["LUX Rust Gateway"]
            CLI["lux CLI"]
            HTTP["Axum HTTP API"]
            WS["WebSocket events"]
            MCP["MCP Server"]
            Tools["Tool execution layer"]
            SkillAdapter["Skill Adapter"]
        end

        subgraph State[".lux Workspace - SSoT"]
            Spec["Specs"]
            Tickets["Tickets / Kanban"]
            Events["Event logs / Sessions"]
            Builds["Builds / Verification"]
            Roadmap["Roadmap"]
        end

        subgraph Engine["Engine project"]
            Bridge["Bridge adapter"]
            Runtime["Engine runtime / editor"]
            Context["Context / Selection / Logs"]
            Play["Play mode / Input / Capture"]
        end
    end

    Claude --> CLI
    OpenCode --> CLI
    Codex --> CLI
    Other --> HTTP
    Other --> MCP

    CLI --> HTTP
    MCP --> Tools
    HTTP --> Tools
    Tools --> State
    SkillAdapter --> Tools
    Tools --> Bridge
    Bridge --> Runtime
    Runtime --> Context
    Runtime --> Play
    Bridge --> Tools
    Tools --> WS

LUX is context-first, not vision-first. It standardizes the evidence an AI agent needs before editing or claiming a game behavior:

Common commands:

# Install and run the gateway
cargo install --path gateway
lux serve

# Initialize a target project and install the Unity bridge
cd /path/to/your/project
lux init
lux bridge install --project-path /path/to/your/unity-project

# Unity status and verification
lux unity status
lux unity context
lux unity compile
lux unity run-tests
lux unity play
lux unity screenshot

# Specs, roadmap, tickets, and GitHub issues
lux spec
lux spec edit gdd
lux spec validate
lux roadmap status
lux kanban
lux verify

# Skills and logs
lux skill list
lux skill info my-skill
lux ai-log recent
lux ai-log tail

Representative API surfaces:

Game intent and domain decisions live under .lux/specs/. README files and docs/ are readable projections of that state. Actual game requirement changes should be recorded through the defined .lux/specs/spec.json, .lux/specs/gdd.md, .lux/specs/domains/*.md, and .lux/specs/decisions.jsonl write paths.

Lux/
├── gateway/                        # Rust CLI + Axum HTTP/WS server
│   ├── src/
│   │   ├── main.rs                 # CLI entry point
│   │   ├── server.rs               # Axum router
│   │   ├── protocol.rs             # Event envelope and bridge protocol
│   │   ├── project.rs              # Unity project detection
│   │   ├── project_godot.rs        # Godot project detection
│   │   ├── bridge_types.rs         # Bridge type definitions
│   │   ├── godot_bridge_install.rs # Godot bridge install path
│   │   ├── lux_*.rs                # Lux core modules
│   │   ├── uloop_*.rs              # Unity CLI passthrough
│   │   ├── skill_adapter/          # Skill loading and adaptation
│   │   └── templates/              # Gateway-managed templates
│   ├── tests/
│   └── Cargo.toml
│
├── crates/                         # Shared Rust core packages
├── bridge/                         # Engine bridge adapters, in-repo source
│   ├── unity/                      # Unity C# bridge
│   ├── godot/                      # Godot bridge
│   └── threejs/                    # Three.js adapter files
├── Skills/                         # Skill source tree
├── docs/                           # Human-readable docs and ADRs
├── scripts/                        # Verification and maintenance scripts
├── Cargo.toml
├── Cargo.lock
└── LICENSE

The minimal runtime roadmap and milestone status lives in .lux/roadmap.json. User/game requirements, execution tickets, and active run state live under the ADR-003 domain paths such as .lux/specs/spec.json, .lux/specs/domains/*.md, .lux/tickets/*.json, and .lux/run-state.json.

Repository-level Lux roadmap work and unaddressed product features are tracked in GitHub Issues. Local .ledger-style files are only for local worktree decision recording; they must not become the roadmap backlog or collaborator-visible feature registry.

Out of scope for the current public-beta framing:

• Automatic GitHub milestone/issue sync unless a supported GitHub issue-registration surface is implemented.
• WebRTC or remote video streaming unless explicitly gated behind experimental flags.
• Browser-based remote control of Unity Editor.
• iOS companion app or PWA.
• Windows/Linux editor support beyond documented capability tiers.

The repository follows six invariants adapted from alex-core-invariants:

Allowed transition markers:

• // lux-allow-failover
• // lux-allow-legacy
• // lux-allow-dual-write

# Rust
cargo build --workspace
cargo test --workspace

# Project checks
bash scripts/check-project-structure.sh
bash scripts/check-readme-bridge-contract.sh
bash scripts/test-all.sh --quick

# CLI help
cd gateway && cargo run -- bridge install --help
cd gateway && cargo run -- serve --help

Unity bridge tests require Unity Editor and should be run through the Unity Test Runner for the bridge package.

Copyright (c) 2024-2026 Linalab. All rights reserved.