Nethercore ZX Game Development

Overview

Nethercore ZX is a fantasy console targeting 5th-gen aesthetics (PS1/N64/Saturn) with rollback netcode. Games compile to WASM and run in the Nethercore player.

Specifications:

• Resolution: 960×540 (fixed, 16:9)
• Tick Rate: 24/30/60/120 fps
• ROM Size: 16MB max
• WASM Memory: 4MB (auto-snapshotted)
• VRAM: 4MB
• Players: 1-4 (local + remote)
• Coordinate System: Y-up, right-handed, -Z forward

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

Project Setup

See shared/file-organization.md for project structure and shared/build-workflow.md for build commands.

Key principle: Keep entry files minimal (~50 lines). FFI bindings in separate module file (zx.rs/zx.h/zx.zig).

FFI Reference

The FFI provides 250+ functions across these categories:

Always read nethercore/include/zx.rs for accurate signatures.

Init-Only Functions

Must call only during init():

• set_tick_rate(rate) - 0=24fps, 1=30fps, 2=60fps, 3=120fps
• set_clear_color(color) - 0xRRGGBBAA
• render_mode(mode) - 0=Lambert, 1=Matcap, 2=PBR, 3=Hybrid
• All rom_*(), load_*(), procedural mesh functions

Render Modes

Normal Maps

Normal maps add surface detail without increasing geometry. Use in any render mode.

Material binding:

material_albedo(albedo_tex);    // Slot 0
material_mre(mre_tex);          // Slot 1
material_normal(normal_tex);    // Slot 3

Requirements:

• Mesh must have tangent vertex data (FORMAT_TANGENT = 16)
• Normal map texture (BC5 auto-compressed from *_normal.png)

Skip normal map:

skip_normal_map(1);  // Use vertex normal instead

See procedural-normal-maps skill for generation.

Rollback Safety

See shared/rollback-rules.md. Key points:

• All state in static variables
• Use FFI random() not external RNG
• Use tick_count() not system time
• Never modify state in render()

Documentation