Quick recipes
1. Remove the crosshair
// in the game module
config: { hud: { crosshair: { enabled: false } } }
or at runtime: app.hud.setCrosshair(false).
2. Turn the crosshair into a small dot
config: { hud: { crosshair: { style: 'dot', size: 8, thickness: 2, color: '#ffb347' } } }
3. Toggle-style crouch (instead of holding the key)
config: { player: { crouch: { mode: 'toggle', toggleKey: 'KeyC' } } }
Listen with: app.events.on('player:crouch', ({ crouched }) => ...).
4. Change the crouch key
config: { input: { binds: { crouch: ['KeyX'] } } }
Note: changing binds.crouch does not change player.crouch.key (that one is only for documentation/display).
5. Start in third-person view
config: { player: { view: { mode: 'tp', distance: 4.2, height: 1.6 } } }
6. Add a patrolling NPC
import { npcPlugin } from 'risejs-core/packs/npc';
build(app) {
app.use(npcPlugin);
app.spawnNpc({
path: [[-10, 0, -6], [10, 0, -6], [10, 0, 6]],
speed: 1.4,
pause: 1.5,
color: 0x2f4b6b,
name: 'guard',
});
}
7. Add an object with collision
import { box } from 'risejs-core';
build(app) {
app.add(box({ size: [3, 2, 3], position: [4, 1, -8], color: 0x555c64, tags: ['cover'] }));
}
The collider is computed automatically once the mesh has world coordinates.
8. Add a sample game (in the repository)
npm run create-game -- canyon
# demo shell only: open http://localhost:5173/?game=canyon (the framework does not read the URL; your own project uses createApp({ game }))
9. Turn off the flashlight / change the sunlight
config: {
lights: {
torch: { enabled: false },
sun: { intensity: 4.2, color: '#ffd0a0', position: [-30, 28, 20] },
},
}
10. Create a grass field and a pond
import { SurfaceMap, SURFACE } from 'risejs-core';
const surface = new SurfaceMap();
surface.rect(SURFACE.GRASS, 0, 20, 30, 20);
surface.circle(SURFACE.WATER, -20, 0, 8);
app.world.setStatic(root, colliders, surface);
11. Quick tweaks during development
The framework does not read the URL (players must not be able to change config). Pass values through createApp:
createApp({ game, config: { render: { fog: 0.004, exposure: 1.5, fov: 82 }, player: { view: { mode: 'tp' } } } });
12. Stationary NPC (turns its head only)
// needs app.use(npcPlugin)
app.spawnNpc({ path: [[0, 0, -6]], speed: 0 });
13. Add your own HUD element
const el = document.createElement('div');
el.className = 'stats';
el.style.bottom = '56px';
el.textContent = 'AMMO ∞';
app.hud.root.appendChild(el);
14. Run 2 games in 2 tabs
In the repository's demo shell, open each sample game in its own tab (?game=city, ?game=foundry; demo only, the framework does not read the URL).
In your own project, call createApp({ game }) in each page.
15. Capture a still frame
Set config.time.still = true to render a paused scene and config.render.preserveDrawingBuffer = true so the canvas can be
read back, then call app.renderer.domElement.toDataURL('image/png'). Press F1 to show the debug figures.
16. Add an interact key (E) and fire (left mouse button)
These actions already exist in the default config — just read them:
tick(dt, app) {
if (app.input.justPressed('interact')) {
app.hud.setHint('Interacted');
}
if (app.input.down('fire')) {
// fire
}
if (app.input.justPressed('reload')) {
// reload
}
}
Change the keys:
config: { input: { binds: { interact: ['KeyF'], fire: ['Mouse0', 'KeyJ'] } } }
17. Pick up items & interact (inventory pack)
import { inventoryPlugin } from 'risejs-core/packs/inventory';
build(app) {
app.use(inventoryPlugin, { capacity: 8 });
const crate = box({ size: [0.8, 0.8, 0.8], position: [6, 0.4, 4], color: 0x8a5a2b });
app.add(crate);
app.interaction.add(crate, {
label: 'Pick up crate',
range: 2.8,
onUse: () => {
app.inventory.add({ id: 'supply', name: 'Supply crate' }, 1);
app.world.remove(crate);
},
});
}
- The prompt appears when you stand near the object and look at it (dot > 0.15).
- Open the inventory with I.
- Events:
inventory:add,inventory:change.
18. Dialogue & quests (quest pack)
import { questPlugin } from 'risejs-core/packs/quest';
const graph = {
intro: {
speaker: 'MARA',
text: 'Can you pick up three crates for me?',
choices: [
{ label: 'Accept', next: 'ok', action(app) {
app.quests.add({ id: 'supply', title: 'SUPPLIES',
steps: [{ id: 'crates', text: 'Collect crates', need: 3 }] });
} },
{ label: 'Later', next: null },
],
},
ok: { speaker: 'MARA', text: 'Good.', choices: [{ label: 'Got it', next: null }] },
};
app.use(questPlugin);
app.dialogue.start(graph, 'intro');
app.quests.progress('supply', 'crates', 1);
- Dialogue: keys 1–9 or click; Esc closes; the game switches to the
dialoguestate automatically. - Events:
quest:progress,quest:complete.
19. Grid movement (grid pack)
import { gridPlugin } from 'risejs-core/packs/grid';
app.use(gridPlugin, { cell: 3, stepTime: 0.18, repeat: 0.24, min: [-6, -6], max: [6, 6] });
app.events.on('grid:step', ({ i, j }) => console.log('cell', i, j));
app.events.on('grid:blocked', () => app.audio.play('error'));
app.grid.cell; // { i, j }
app.grid.moveTo(5, -5);
Sample game: tactics (run from the repository's demo shell) — a 13×13 grid, the target cell glows.
20. Positional audio (audio3d pack)
import { audio3dPlugin } from 'risejs-core/packs/audio3d';
app.use(audio3dPlugin);
app.audio3d.playAt('hit', { x: 0, y: 0.4, z: -34 });
The listener follows the camera every frame. Requires audioPlugin (enabled by default).
21. Save with D1 over HTTP
import { persistencePlugin } from 'risejs-core/packs/persistence';
app.use(persistencePlugin, { base: 'http://127.0.0.1:8787', game: app.id, player: 'p1' });
await app.remote.auth();
const { data } = await app.remote.read();
await app.remote.write({ score: 10 });
await app.remote.event('teleport', { d: 40 }); // telemetry → events table
The server must be running (npm run server). To require auth: --var AUTH_REQUIRED:1.
22. Prepare for multiplayer
import { zoneKey, neighborKeys } from 'risejs-core';
zoneKey(70, 130); // "1,2"
neighborKeys(70, 130, 64, 1); // 9 zones around the player
See networking.md for the full protocol and architecture.
23. 3-channel chat + nameplates (chat, nameplate packs)
import { chatPlugin } from 'risejs-core/packs/chat';
import { nameplatePlugin } from 'risejs-core/packs/nameplate';
app.use(nameplatePlugin);
app.use(chatPlugin); // needs the net pack to send/receive
app.nameplates.add(npc, { name: 'MARA' });
app.nameplates.say(app.nameplates.items.get(npc), 'Hello', 3);
app.chat.ignore('spammer'); // hide messages from this player
T opens the input box, Enter sends, Esc closes. Commands: /all …, /zone …, /w name ….
Banned words are masked by default (blocked) and repeated messages are blocked (SpamGuard).
24. NPC AI with pathfinding (npc pack + navmesh)
import { npcPlugin, NpcAgent } from 'risejs-core/packs/npc';
import { NavGrid } from 'risejs-core/packs/navmesh';
app.use(npcPlugin);
app.spawnNpc({ path: [[0, 0, 0], [10, 0, 0]], speed: 1.4 }); // patrol
const nav = new NavGrid({ cell: 1, minX: -60, maxX: 60, minZ: -60, maxZ: 60 });
for (const c of world.colliders) if (c.max.y > 1.2) nav.blockBox(c);
const guard = new NpcAgent({ path: [[0, 0, 0], [12, 0, 0]], sight: 16, nav });
app.world.add(guard);
app.spawnNpc is not in core — you must call app.use(npcPlugin) first (NPC behavior is a pack).
States: patrol → chase → return; guard.goTo(point) returns an array of A* waypoints.
25. Falling objects & vehicles (physics pack)
import { Body, stepBody, Vehicle } from 'risejs-core/packs/physics/body';
const crate = new Body({ x: 0, y: 6, z: 0, restitution: 0.4 });
crate.impulse(2, 0, -3);
app.events.on('frame', (dt) => stepBody(crate, dt, { groundY: (x, z) => app.world.heightAt(x, z) }));
const car = new Vehicle({ x: 0, z: 0 });
car.update(dt, { throttle: 1, steer: -0.4 }); // every frame
No extra dependency: enough for falling crates, bouncing balls, and kinematic vehicles.
26. Lobby & quick match (lobby pack)
app.use(lobbyPlugin, { url: 'http://127.0.0.1:8787' });
const room = await app.lobby.quickMatch(); // picks the room with the fewest players
L opens the list, Q quick match. Server: POST /api/rooms (heartbeat, TTL 60 s),
GET /api/rooms → { rooms, total, open }.
27. Measure real fps (bench pack)
import { benchPlugin } from 'risejs-core/packs/bench';
app.use(benchPlugin, { seconds: 10 }); // report: app.bench.report
The overlay shows fps, p50/p95/1% low, % jank, draw calls, triangles. F4 downloads JSON.
28. Load an external model (gltf pack)
import { loadGltf, prefabFromGltf, attachAnimations } from 'risejs-core/packs/gltf';
const gltf = await loadGltf('/models/crate.glb');
app.add(prefabFromGltf(gltf, { scale: 0.9, tags: ['solid'] })({ pos: [2, 0.5, 3], rotY: 0.4 }));
const anim = attachAnimations(gltf, gltf.scene);
anim.play('idle');
app.events.on('frame', (dt) => anim.update(dt));
You need a real .glb; the repo has a sample at public/models/crate.glb (npm run make:glb).
29. Accessibility & PWA
import { a11yPlugin } from 'risejs-core/packs/a11y';
app.use(a11yPlugin);
app.a11y.set({ colorblind: 'deuteranopia', uiScale: 1.2, reduceMotion: true });
a11y settings are stored in localStorage['rise.a11y']; they are not read from the URL. PWA: public/manifest.webmanifest +
public/sw.js (registered only in PROD); icons live in public/.
30. Seeded RNG & tween
import { Rng } from 'risejs-core';
const rng = new Rng('city'); // or app.rng (createApp({ seed }))
rng.int(1, 6); rng.pick(['a','b']); rng.shuffle(list);
rng.weighted([['common', 80], ['rare', 20]]);
app.tween.to({ from: 0, to: 1, duration: 0.4, ease: 'backOut', onUpdate: (v) => (x = v) });
Tweens run every frame automatically; EASING has 10 types.
31. Combat with health (combat + vfx packs)
app.use(vfxPlugin);
app.use(combatPlugin);
app.combat.register(npc, { hp: 60, team: 2 });
app.combat.register({ pos: app.player.pos, mesh: { position: app.player.pos } }, { hp: 100, team: 1, bar: false });
const res = app.combat.strike(playerRef, { damage: 22, range: 2.8, arc: 0.8 });
// res = { target, applied, dead } | null
The health bar appears above the head when hp < max; damage numbers + hit flash are automatic if vfx is installed.
32. RPG: stats, XP, effects (stats + loot packs)
import { Stats, Progression, StatusEffects } from 'risejs-core/packs/stats/core';
import { CRATE_LOOT } from 'risejs-core/packs/loot/core';
const stats = new Stats({ str: 10 });
stats.modifier({ stat: 'str', value: 0.2, mode: 'mul' });
const xp = new Progression({ level: 1 });
xp.addXp(120); // → level 2
const fx = new StatusEffects();
fx.add({ id: 'burn', duration: 4, dot: 6 });
fx.tick(dt); // { damage, heal, expired }
const drops = CRATE_LOOT.roll(app.rng, { luck: 0.1, rolls: 3 });
33. Visual novel (vn pack)
app.use(vnPlugin);
app.vn.start({
start: 'a',
nodes: {
a: { speaker: 'MARA', portrait: 'F', expression: 'happy', text: 'Hello.', next: 'b' },
b: { text: 'Shall we go?', choices: [
{ label: 'Go', next: null, action: (app) => app.loadLevel('/levels/city.json') },
{ label: 'Stay', next: null },
] },
},
});
Space advances · B backlog · A auto · Ctrl skip · 1–9 choose.
34. Weather & day/night
app.use(weatherPlugin);
app.weather.set('rain'); // clear | rain | snow
app.weather.time = 0.75; // 0..1 (night)
Console (with consolePlugin): weather snow, time 0.2.
35. Seeded map generation (procgen pack)
import { generateRooms, scatter, makeNoise } from 'risejs-core/packs/procgen/core';
const { rooms, corridors } = generateRooms(app.rng, { count: 8, width: 96, height: 96 });
const trees = scatter(app.rng, { count: 60, width: 200, height: 200, minDist: 6 });
const noise = makeNoise('city').fbm;
Same seed → same map. Pass createApp({ seed }) to reproduce the same map.
36. Replay & dev console
app.use(replayPlugin);
app.replay.start();
const json = app.replay.stop(); // { tickMs, seed, frames }
app.replay.load(json); // play back
Console: app.use(consolePlugin) → (backquote) opens it;help, give ammo 10, spawn npc, weather rain, time 0.8, level /levels/a.json. Debug: app.use(debugPlugin)` → F6 colliders, F7 stats, F8 navmesh.
37. Load a level with fade
game.onLevel = (level, app) => { /* build entities from level.entities */ return level.entities.length; };
await app.loadLevel('/levels/park.json');
Without onLevel, it uses applyLevel + the default prefab registry.
38. Terrain from a heightfield (terrain pack)
import { Terrain } from 'risejs-core/packs/terrain';
import { Heightfield } from 'risejs-core/packs/physics/heightfield';
const field = new Heightfield({ width: 128, height: 128, heights });
const terrain = new Terrain({ heightfield: field, size: 200, segments: 96 });
app.scene.add(terrain.mesh);
Color is lerped by height (low → mid → high → peak); call terrain.dispose() when changing maps.
39. Autotile & equipment
const map = new Tilemap({ texture, cols, rows, tile: 1, data, solids: [1] });
map.applyAutotile({ family: 1, base: 4 }); // strip of 16 variants, 4 directions
app.inventory.add({ id: 'sword', name: 'Sword', stats: { str: 3 }, slot: 'weapon' }, 1);
app.inventory.equip('sword'); // slot defaults to 'weapon'
app.inventory.bonus(); // { str: 3 }
In the inventory panel: 1–8 select a slot, R equips/unequips.
40. Preload assets with progress (assets pack)
app.use(assetsPlugin, { base: '/assets/' });
await app.assets.load(['tex/tile.png', 'sfx/hit.ogg', 'models/crate.glb'], {
onProgress: (ratio, entry) => hud.setHint(`Loading ${Math.round(ratio * 100)}%`),
});
const tex = app.assets.texture('tex/tile.png');
const gltf = await app.assets.gltf('models/crate.glb');
Cached by URL; one failed file does not block the others (returns { ok, failed, total }).
41. Background music, fade and duck (music pack)
app.use(musicPlugin);
app.music.play('calm'); // calm | tense | dark | victory
app.music.duck(true); // lowers automatically while dialogue/VN is open
app.music.stop(1.5);
No files needed: 4 chords synthesized with WebAudio (oscillator + lowpass + LFO).
You can pass { buffer } to play pre-recorded music.
42. Fixed step for deterministic simulation
game.config = { time: { fixed: 60, maxSteps: 5 } };
When fixed > 0, position/physics run in 1/60 s steps (accumulator), while game.tick and rendering
still follow the frame. A backlog larger than maxSteps is dropped to avoid a spiral of death.
43. Versioned save + migrate
const slot = new SaveSlot({
gameId: 'rpg',
version: 2,
migrate: {
1: (data) => ({ ...data, coins: (data.coins || 0) * 100 }),
},
});
const { data, migrated, from } = await slot.read();
The migrate chain runs v1→v2→…; a missing step → reason: 'migrate-missing'. A newer save → 'version-newer'.
44. Editor export/import
Sample game editor (repository demo shell) → place objects, Ctrl+S saves to localStorage, Ctrl+E downloads a .json,
Ctrl+I imports a file. API: app.editor.exportFile(), importData(json), serialize().