AGENTS.md

CRITICAL: This file contains the engineering context for AI coding agents.

🚨 Absolute Rules (Never Break These) / Do Not

DO NOT bypass the Lua scripting layer for gameplay logic.
DO NOT use unwrap() or expect() outside main or tests.
DO NOT use println!; use tracing.
DO NOT introduce non-deterministic logic into worldgen (no thread_rng, no HashMap iteration).
DO NOT build parallel registration systems or duplicate registries.

📖 What to Read

Read AGENTS.md (this file) first for every task.
Read DEVELOPMENT.md before making any architectural or cross-cutting changes.
Read subsystem docs (docs/ and rustdoc) only for the specific crates you are modifying.

✅ Before Changing Code

Does this require updates to documentation or ADRs (docs/adr/)?
Which crate does this belong to? (Maintain strict boundaries).
Is this a new gameplay feature? If so, it must be exposed via the Lua API.

🛠️ Modification Priorities

Implement the feature in Lua if possible, using existing APIs.
Extend the Lua API if it lacks the required capability.
Modify Rust internals only as a last resort to support the Lua API. Avoid bypassing the scripting layer entirely for gameplay features.

🏗️ Code Style & Edits

Prefer modifying existing systems over creating new abstractions.
Avoid duplicate registries, parallel APIs, unnecessary traits, and premature generic abstractions.
Keep changes local to the relevant module unless the architecture requires otherwise.

❓ When Unsure

If an implementation conflicts with these rules, prefer preserving the architecture over minimizing code changes.

📦 Architectural Dependency Rules

shared stays lean and dependency-light (no mlua, no rendering).
scripting depends on shared, but shared does not depend on scripting.
client and server depend on shared, scripting, and net.
client depends on renderer, but server does not.
Do not put simulation logic in client.

🔍 File Location Hints

/assets/scripts/: Shipped base game Lua scripts.
/mods/: In-repo example mods/test fixtures.
<user-data-dir>/mods/: Player-installed mods (resolved at runtime).
crates/client/: Windowing, input, presentation.
crates/server/: Authoritative simulation.
crates/shared/: Core types, network protocols.
crates/scripting/: Lua API bindings.
crates/renderer/: Vulkan graphics.
crates/net/: QUIC networking.

⚙️ Basic Verification Commands

Check compilation: cargo check -p <crate>
Lint code: cargo clippy --all-targets --all-features -- -D warnings
Format Rust: cargo fmt --all -- --check
Format Lua: stylua . and selene .
Run tests: cargo test -p <crate>

🚀 Quick Start Task Checklist

Review "What to Read" and "Before Changing Code".
Check modification priorities (Lua vs Rust).
Make edits following code style guidelines.
Run basic verification commands.
Commit using Conventional Commits.

Additional Subsystem Context

Concurrency & State

Multithreaded: Prefer message-passing and per-thread ownership over shared mutable state. Avoid large Mutex wrappers.
Vulkan queues: Not free-threaded.
Lua VMs: Not thread-safe. Treat each VM as owned by a single thread.

Determinism

Worldgen: Strictly seed-deterministic. Use fixed RNG algorithms (wyrand, xoshiro). Never use rand::thread_rng(). Do not rely on HashMap iteration order (use BTreeMap or IndexMap).
Simulation: Server-authoritative but not lockstep. Platform-specific math and floats are permitted outside of worldgen.

Logging & Error Handling

Logging: Use tracing and spans (#[tracing::instrument]). No println!.
Libraries (shared, renderer, scripting): Use thiserror.
Binaries (client, server): Use anyhow.

Testing Expectations

Test pure algorithmic logic, correctness traps (e.g. integer overflow, div_euclid), and determinism (worldgen).
I/O and GPU code are tested via integration/visual verification.
Ensure new tests run successfully and do not break existing ones.

Linting

The workspace uses strict lints (including banning unwrap, expect, print).
Prefer #[expect(...)] over #[allow(...)]. Suppress narrowly and justify non-obvious suppressions. Never suppress correctness lints.

Documentation Style

Formal, objective tone. No "we" or "you".
All public/internal struct fields need /// docs.
Functions require # Errors, # Panics, and # Safety sections in that order.

Branching Strategy

Development branch: dev.
Releases branch: main.
Large features: Feature branch off dev (e.g., feat/new-worldgen).

General Coding Standards

Content IDs: Strict "namespace:id" format (e.g. "core:stone"). Interned to handles at runtime.
Coordinate system: +Y up, right-handed. 1 unit = 1 block (0.5m).
Paths: Linux/Windows only. Use std::path::Path and directories crate. No hard-coded /home.
Commits: Conventional Commits with crate scope (e.g., feat(scripting): ...).

5.1 KiB Raw Blame History