tomevault-io Nethercore Development
Overview
Nethercore games compile to WASM and run in the Nethercore player with rollback netcode. All consoles share the same WASM core, ensuring determinism across platforms.
Required Game Exports
Every game exports three functions:
#[no_mangle] pub extern "C" fn init() { } // Setup, asset loading
#[no_mangle] pub extern "C" fn update() { } // Deterministic logic
#[no_mangle] pub extern "C" fn render() { } // Drawing only
nether CLI
| Command | Purpose |
|---|---|
nether init |
Create nether.toml manifest |
nether compile |
Compile WASM from source |
nether pack |
Bundle WASM + assets into ROM |
nether build |
compile + pack (main command) |
nether run |
Build and launch in player |
Game Manifest (nether.toml)
[game]
id = "my-game"
title = "My Game"
author = "Your Name"
version = "1.0.0"
[build]
script = "cargo build --target wasm32-unknown-unknown --release"
wasm = "target/wasm32-unknown-unknown/release/my_game.wasm"
[[assets.textures]]
id = "player"
path = "assets/player.png"
Netcode (What You DON'T Do)
The Nethercore player handles all networking automatically:
- GGRS rollback synchronization
- State snapshots
- Input transmission
- Desync detection
Your only responsibility: Make update() deterministic.
Never write: Networking code, rollback logic, state sync, or input transmission.
Determinism (Rollback Safety)
The update() function must be deterministic for rollback netcode. Given identical inputs, all clients must produce identical state.
Rules
- All state in WASM memory - Use static variables (auto-snapshotted)
- Use FFI
random()functions - Never external randomness - Use
tick_count()not system time - Frame-based logic only - render() is display-only - Never modify game state in render
Forbidden Patterns
| Pattern | Problem | Correct Alternative |
|---|---|---|
rand::thread_rng() |
External RNG | FFI random(), random_range() |
SystemTime::now() |
System clock | FFI tick_count() |
HashMap iteration |
Unordered | Arrays, BTreeMap |
| State changes in render() | Skipped during rollback | Move to update() |
Quick Test
nether run --sync-test --frames 1000
If this fails, you have non-deterministic code.
Project Structure
my-game/
├── nether.toml # Game manifest
├── src/
│ ├── lib.rs # Entry point (init/update/render)
│ └── zx.rs # FFI bindings (console-specific)
├── assets/
│ ├── textures/
│ ├── meshes/
│ └── audio/
└── Cargo.toml
Key principle: Keep entry files minimal (~50 lines). FFI bindings in separate module.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.