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:
| Category |
Key Functions |
Find In zx.rs |
| System |
delta_time, tick_count, log |
Lines 1-100 |
| Random |
random, random_range, random_f32 |
Search "random" |
| Input |
button_held, button_pressed, left_stick_x |
Search "button" |
| Camera |
camera_set, camera_fov |
Search "camera" |
| Transforms |
push_translate, push_rotate_y, push_scale |
Search "push_" |
| Meshes |
load_mesh, draw_mesh, cube, sphere |
Search "mesh" |
| Textures |
load_texture, texture_bind |
Search "texture" |
| Materials |
material_albedo, material_mre, material_normal |
Search "material" |
| Audio |
load_sound, play_sound, music_play |
Search "sound" |
| 2D Drawing |
draw_sprite, draw_text, draw_rect |
Search "draw_" |
| Environment |
draw_env, env_gradient |
Search "env_" |
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=120fpsset_clear_color(color) - 0xRRGGBBAArender_mode(mode) - 0=Lambert, 1=Matcap, 2=PBR, 3=Hybrid- All
rom_*(), load_*(), procedural mesh functions
Render Modes
| Mode |
Name |
Use Case |
| 0 |
Lambert |
Flat colors, 2D, stylized |
| 1 |
Matcap |
Sculpted look, toon |
| 2 |
PBR |
Realistic (default) |
| 3 |
Hybrid |
PBR + matcap |
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
| Resource |
Location |
| FFI Source |
nethercore/include/zx.rs (canonical) |
| Cheat Sheet |
nethercore/docs/book/src/cheat-sheet.md |
| Tutorials |
nethercore/docs/book/src/tutorials/paddle/ |
| Examples |
nethercore/examples/ |
1---2name: nethercore-zx-game-development3description: This skill provides ZX game development guidance. Triggers on "create ZX game", "ZX FFI", "nether build", "nether.toml", "ZX graphics/audio", "WASM game". **Load references when:** - Project setup → `shared/file-organization.md`, `shared/build-workflow.md` - Code examples → `examples/hello-world-rust.md`, `examples/game-with-assets.md` - Coordinate math → `references/coordinate-conventions.md` - Common patterns → `references/quick-patterns.md` - FFI details → Read `nethercore/include/zx.rs` directly4---5
6# Nethercore ZX Game Development
7
8## Overview
9
10Nethercore 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.
11
12**Specifications:**
13- Resolution: 960×540 (fixed, 16:9)
14- Tick Rate: 24/30/60/120 fps
15- ROM Size: 16MB max
16- WASM Memory: 4MB (auto-snapshotted)
17- VRAM: 4MB
18- Players: 1-4 (local + remote)
19- Coordinate System: Y-up, right-handed, -Z forward
20
21## Required Game Exports
22
23Every game exports three functions:
24
25```rust
26#[no_mangle] pub extern "C" fn init() { } // Setup, asset loading
27#[no_mangle] pub extern "C" fn update() { } // Deterministic logic
28#[no_mangle] pub extern "C" fn render() { } // Drawing only
29```
30
31## Project Setup
32
33See `shared/file-organization.md` for project structure and `shared/build-workflow.md` for build commands.
34
35**Key principle:** Keep entry files minimal (~50 lines). FFI bindings in separate module file (`zx.rs`/`zx.h`/`zx.zig`).
36
37## FFI Reference
38
39The FFI provides 250+ functions across these categories:
40
41| Category | Key Functions | Find In zx.rs |
42|----------|--------------|---------------|
43| System | `delta_time`, `tick_count`, `log` | Lines 1-100 |
44| Random | `random`, `random_range`, `random_f32` | Search "random" |
45| Input | `button_held`, `button_pressed`, `left_stick_x` | Search "button" |
46| Camera | `camera_set`, `camera_fov` | Search "camera" |
47| Transforms | `push_translate`, `push_rotate_y`, `push_scale` | Search "push_" |
48| Meshes | `load_mesh`, `draw_mesh`, `cube`, `sphere` | Search "mesh" |
49| Textures | `load_texture`, `texture_bind` | Search "texture" |
50| Materials | `material_albedo`, `material_mre`, `material_normal` | Search "material" |
51| Audio | `load_sound`, `play_sound`, `music_play` | Search "sound" |
52| 2D Drawing | `draw_sprite`, `draw_text`, `draw_rect` | Search "draw_" |
53| Environment | `draw_env`, `env_gradient` | Search "env_" |
54
55**Always read `nethercore/include/zx.rs` for accurate signatures.**
56
57## Init-Only Functions
58
59Must call only during `init()`:
60- `set_tick_rate(rate)` - 0=24fps, 1=30fps, 2=60fps, 3=120fps
61- `set_clear_color(color)` - 0xRRGGBBAA
62- `render_mode(mode)` - 0=Lambert, 1=Matcap, 2=PBR, 3=Hybrid
63- All `rom_*()`, `load_*()`, procedural mesh functions
64
65## Render Modes
66
67| Mode | Name | Use Case |
68|------|------|----------|
69| 0 | Lambert | Flat colors, 2D, stylized |
70| 1 | Matcap | Sculpted look, toon |
71| 2 | PBR | Realistic (default) |
72| 3 | Hybrid | PBR + matcap |
73
74## Normal Maps
75
76Normal maps add surface detail without increasing geometry. Use in any render mode.
77
78**Material binding:**
79```rust
80material_albedo(albedo_tex); // Slot 0
81material_mre(mre_tex); // Slot 1
82material_normal(normal_tex); // Slot 3
83```
84
85**Requirements:**
86- Mesh must have tangent vertex data (FORMAT_TANGENT = 16)
87- Normal map texture (BC5 auto-compressed from `*_normal.png`)
88
89**Skip normal map:**
90```rust
91skip_normal_map(1); // Use vertex normal instead
92```
93
94See `procedural-normal-maps` skill for generation.
95
96## Rollback Safety
97
98See `shared/rollback-rules.md`. Key points:
99- All state in static variables
100- Use FFI `random()` not external RNG
101- Use `tick_count()` not system time
102- Never modify state in `render()`
103
104## Documentation
105
106| Resource | Location |
107|----------|----------|
108| FFI Source | `nethercore/include/zx.rs` (canonical) |
109| Cheat Sheet | `nethercore/docs/book/src/cheat-sheet.md` |
110| Tutorials | `nethercore/docs/book/src/tutorials/paddle/` |
111| Examples | `nethercore/examples/` |
majiayu000