NGIN / Creator handbook
Start here
NGIN is alpha and in active development. It is a Three.js WebGPU engine. You describe a game. The AI reuses these modules instead of inventing walking, cars, or water from scratch.
Play the sandbox to feel the defaults. Read a module when you need it. Copy a prompt example. Do not ask the AI to rewrite a module that already exists.
Walking
You describe the game. The AI uses NGIN. Walking is already built: a player who moves, looks, jumps, and crouches on solid ground. Do not ask the AI to invent walking from scratch.
What you get
A person in the world. They walk with W A S D, run with Shift, crouch with C, jump with Space, switch first / third person with V, and toggle a flashlight with L (on foot only).
Look is either drag (hold the left mouse button) or capture (click the canvas, mouse locks until Esc). Pick one in your prompt.
How it feels
Every NGIN game uses the same body. Speeds and heights stay fixed so walking does not turn into a pile of special cases.
Standing is 1.8 m. Crouch is 1.0 m. In third person the body turns while moving and keeps its last facing when idle. Crouch bends the knees. The third-person camera stays at standing height and does not dip.
First person looks through the eyes and moves where the camera faces. Third person orbits behind the character.
The character
The player is a block figure: head, torso, arms, legs. Limbs swing when they walk. This is the NGIN person. Keep it.
Later you will be able to ask for colours, clothes, and attachments (backpack, cap, boots, cape). That is not this module. Do not ask the AI to build a clothing system yet, and do not replace the player with a GLB model.
What to ask for
- Start in first person or third person
- Always run, without holding Shift
- Invert mouse, field of view, look sensitivity
- Drag look or mouse-capture look
- Where the player spawns
- Floors, ramps, stairs, boxes, and walls they can walk on or bump into
- A trampoline that launches the player
- A ground fan that blows up, or turned on its side to blow sideways
What not to ask for
- Custom walking, sliding, or “better” physics for the player
- A different character controller or a skinned player model
- Clothes, hats, backpacks, or recolors (later)
- A world with no floor collider (they will fall through)
Ground rule. Every solid thing the player stands on or runs into needs a matching collider. Say that in the prompt. The AI already knows how to pair a mesh with a collider in NGIN.
Prompt examples
Paste these as-is, then add your level idea.
Use NGIN walking. Third person, always run, drag to look. A small courtyard with stone blocks, one ramp, and a floor I cannot fall through. Do not rewrite walking.
Use NGIN walking. First person, invert mouse, capture look. Quiet walk, hold Shift to run. A 40 metre grass field with a few boxes to jump on. Press V to switch view.
Use NGIN walking. Keep the block character. Spawn on a flat floor with stairs I can walk up. Third person, scroll to zoom.
Use NGIN walking. A trampoline and an upward ground fan, plus one fan on its side that pushes me horizontally. Do not rewrite walking.
Actions
You look at a thing and press a key. The prompt in the middle of the screen tells you which key. Do not ask the AI to invent a second interaction system.
What you get
A look-at prompt. If you are aiming at something usable, the key and the action appear. If you are not looking at it, you cannot use it.
E is for seats. F is for things you can hold. That split is the NGIN rule. Do not make E pick things up.
What to ask for
- A door, crate, vehicle, or switch that shows a prompt when looked at
- Different keys for different jobs (enter vs pick up)
- Prompt text in plain language (“Carry crate”, “Enter car”)
What not to ask for
- Use-on-touch, use-in-radius, or use-the-nearest-object-behind-you
- Hardcoded keys inside each object (the action map already owns the keys)
- A custom raycaster or click-to-select UI for world objects
Prompt examples
Use NGIN actions. Look at a crate to see F Carry and G Stow. Look at a car to see E Enter. Do not add a radius pickup.
Carry
The held item stays in the world, in front of you, and still bumps walls. Scroll moves it closer or farther. Right-mouse drag rotates it. Same idea as Drive Beyond Horizons and The Long Drive.
What you get
Look at an item and press F. It lifts to the hold point: in first person, along your look; in third person, in front of the character. Press F again to drop.
Carry is opt-in. A dynamic body can be pushed around; it is not carryable until you (or the AI) register a look-at F action that grabs it. Green cubes and marbles have physics and cannot be picked up. Orange crates can.
While you hold it, looking around with the left mouse still looks. Right mouse only twists the item. Scroll does not spin it. Entering a vehicle drops it.
What to ask for
- Crates, cans, boxes, or other loose props you can carry
- A hold that you can push into a wall (it should stop, not clip)
- Look-at pickup on that object (F), not a flag on every physics body
What not to ask for
- An
is_carryableflag on rigid bodies. Physics only means it can be shoved. Carry is a separate look-at action. - Gluing the item to the camera or hiding it while carried
- Scroll to rotate, or left-click to rotate
- A second carry button besides F
Prompt examples
Use NGIN carry. Orange crates I can pick up with F. Scroll moves the crate in and out. Right mouse drag rotates it. Drop with F. Do not rewrite carry.
Inventory
Stow makes the item leave the world and sit in a pocket. Numbers put it back in front of you.
What you get
Look at an item and press G, or press G while carrying it. The mesh disappears. A small list shows what you have. Press 1 through 9 to drop that slot at the hold point.
What to ask for
- Pickups that vanish into inventory
- A named slot list (crate, can, battery)
- Drop back into the world with 1–9
What not to ask for
- A grid backpack UI, stacking, or weight limits (not this module)
- Items that stay visible in the world after stow
- A clothing / equipment paper doll (later)
Prompt examples
Use NGIN inventory. I can G stow crates so they disappear, then press 1 to drop one in front of me. Keep the pocket list. Do not build a backpack UI.
Driving
Look at a vehicle, press E, drive with WASD. One seat at a time. Do not ask the AI to write a second car controller.
What you get
Four kinds: car, truck, bus, Kenworth. They share the same driving feel (gears, 4WD, handbrake). Size, mass, and torque change per kind. Tires kick up dust when you move. L toggles headlights while seated. Braking or handbrake brightens the red tails on its own.
Opposite of travel only brakes. After a stop, release the key and press again to change direction. Entering ignores leftover walk keys until you let go of W/S.
What to ask for
- A car, truck, bus, or Kenworth in the level
- Look-at enter with E (pass the interaction system; do not use a radius poll)
What not to ask for
- A custom vehicle physics stack or arcade hover-car
- Driving two vehicles at once
- Replacing the block vehicles with GLB
Prompt examples
Use NGIN driving. A car and a truck I enter with E by looking at them. WASD to drive, Space handbrake. Do not rewrite the vehicle controller.
Towing
The Kenworth comes with a box trailer on a kingpin hitch. That is the NGIN tow. Do not invent a second hitch.
What you get
Cab and trailer are two wheeled bodies. The trailer has no engine. It yaws on the hitch. Cab and trailer do not collide with each other so the hitch does not weld them into one rigid lump.
What to ask for
- A Kenworth with its trailer in the level
What not to ask for
- Hooking the car or truck to a trailer (not this module)
- Detach / attach hitch gameplay (later)
- A rope, chain, or spring tow
Prompt examples
Use NGIN towing. Spawn a Kenworth with its trailer. I drive the cab with E. Do not add a custom hitch.
Boats
Same seat as cars: look, E, then WASD. The hull floats in a water volume. Two kinds: fishing boat and speedboat.
What you get
Fishing boat is slow and damped. Speedboat has more thrust and less drag. Both need water under them (a pool or a water volume). Without water they sit on the ground. Moving hulls throw spray; more speed, more spray.
What to ask for
- A fishing boat or a speedboat on a pool or lake
- A water volume so the hull actually floats
What not to ask for
- Locking the boat to a Y height instead of buoyancy
- A third boat physics system
- Towing a trailer behind a boat
Prompt examples
Use NGIN boats. A pool with a fishing boat and a speedboat. E to drive them. Keep buoyancy. Do not rewrite boat physics.
Physics
Solid things have colliders. Pushable things are dynamic boxes or spheres. The player walks with the built-in character. Do not ask the AI to write a second physics engine.
What you get
Static boxes, convex hulls, and triangle meshes for scenery. Dynamic boxes and spheres you can shove. Water volumes that float anything that enters them. A trampoline bounce pad. A fan that pushes the player and loose objects.
What to ask for
- Floors, walls, ramps, and props with colliders that match the mesh
- Crates, balls, or other shoveable objects
- A trampoline or a fan already in NGIN
What not to ask for
- A custom character controller or a second Jolt world
- Invisible shrink hacks on colliders. If the mesh is the shape, use a mesh collider
Prompt examples
Use NGIN physics. A floor, some static boxes, and a few pushable crates. Do not rewrite the player collider.
GLB models
Load a GLB, clone it into the world, give it a collider. It can be scenery or a thing you pick up. Do not replace the player with a GLB.
What you get
A cached loader and a place helper. Static scenery uses a triangle-mesh collider that follows the model. Loose props use a box collider and can be carryable the same way crates are: look, F, optional G to stow.
What to ask for
- A building or prop GLB with a mesh collider
- A small GLB you can carry, like a crate
What not to ask for
- A skinned GLB as the player
- Shrinking an AABB so you can walk through the eaves. Use the mesh collider
- Replacing the block cars or boats with GLB (not this module)
Prompt examples
Use NGIN GLB models. Place the building with a mesh collider. Do not use a shrink box. Do not replace the player.
Water
A water volume floats bodies that are inside it. A pool is a hole in the ground with that volume in it. Boats need this volume. Do not lock a hull to a Y height.
What you get
An AABB water volume and a waving surface. The sandbox pool is a rectangle cut out of the grass, with a concrete basin. Anything dynamic that sits in the volume floats, including boats and a beach ball.
What to ask for
- A pool or a lake volume with a surface
- Boats that actually float (see Boats)
What not to ask for
- Fake float by pinning Y
- A second buoyancy system
Prompt examples
Use NGIN water. A pool in the ground with a fishing boat and a speedboat. Keep buoyancy. Do not rewrite water.
Day / night
The sky already has a sun, a moon-ish night, and a cycle you can turn on. Do not ask the AI to invent a second time-of-day system.
What you get
Named looks: overcast, sunny, dusk, night, industrial. Optional cycle: midnight, dawn, noon, dusk, back to night. The sun moves. Fog and exposure follow. Night is navy, not pitch black.
What to ask for
- A fixed time of day (noon, dusk, night)
- A day/night cycle that runs while you play
What not to ask for
- A custom sky shader or a second sun
- Keeping night as bright as day
Prompt examples
Use NGIN day and night. Start at dusk. Turn the cycle on. Do not write a new sky system.
Textures & PBR
A folder of maps becomes one metalness/roughness material. Albedo, metallic, roughness, OpenGL normal, AO, height. Do not ask the AI to invent a second PBR stack.
What you get
Drop a FreePBR bl set into assets/textures/name/ as albedo.png, metallic.png, roughness.png, normal.png, ao.png, height.png. The sandbox boxes use four of these. Metals reflect the sky from a map on the material, not a scene-wide environment (that washes the whole level). Night dims that map so the boxes go dark with the rest of the level. Height displaces face interiors only; box UV seams stay pinned so corners do not open. The sandbox Textures → displacement slider is live (0–0.2, default 0.045) so you can see more relief without reloading.
What to ask for
- A prop or box with a PBR set from assets/textures/
- All six maps wired (not albedo-only)
What not to ask for
- Unity smoothness packs or DirectX normals (use the Blender /
blzip) - A custom shader graph for one material
scene.environmentfor one metal (it brightens everything)- Welding or triplanar-displacing a UV-mapped box. Pin the seams; displace face interiors
Prompt examples
Use NGIN PBR. Put the oily-tubework set on those crates. Use every map. Do not write a new material system.
Lighting
One sun (directional, with shadows), a sky/ground hemisphere, a little ambient, and local point lights. Fog is part of the same look. Grass and props use lit materials so night darkens them.
What you get
PBR materials that take lights and fog. Night dims PBR reflections with the sun. A campfire point light. A flashlight on the player (L on foot). Vehicle headlights also use L while seated; brake lights brighten when you brake. Distance fog that thickens at night. Sun shadows follow the camera, so a bigger map does not clip them. Do not unlit-hack the ground so it stays day-bright after sunset.
What to ask for
- A campfire or lamp that lights a small area
- A flashlight on the player, toggle with L while walking
- Vehicle headlights on L while seated, automatic brake lights
- Thicker or thinner fog
- Night with a navy sky, not pitch black
What not to ask for
- Unlit grass or basic materials for the ground
- A second flashlight system. Toggle with L on foot
- A second renderer or baked lightmaps (not this module)
- A huge world-fixed shadow map to cover the whole level. Shadows follow the camera
Prompt examples
Use NGIN lighting. Night, fog, a campfire I can see by. Grass should go dark. Do not use unlit ground.
Particles
Named puff types. Fire, smoke, sparks, a hose spray, tire dust, boat wake. Do not ask the AI to write a second particle system.
What you get
Camera-facing puffs. They fade into fog (fire does not glow through it). The campfire is fire + sparks + smoke. The fountain is a hose spray. Cars kick up dust from the tires by speed. Boats throw wake spray by speed.
What to ask for
- A campfire (fire, sparks, smoke)
- A hose or fountain spray
- Tire dust on a vehicle, wake spray on a boat
What not to ask for
- A GPU particle compute system or a sprite-sheet editor
- Tire or wake particles that ignore speed
Prompt examples
Use NGIN particles. Campfire with fire, sparks, and smoke. Tire dust on the cars. Wake spray on the boats. Do not write a new particle engine.
Snow & rain
Camera-local weather. Rain is vertical streaks. Snow is camera-facing flakes. Toggle them in the sandbox. Do not ask the AI to write a second weather system.
What you get
Rain and snow follow the camera, recycle when you walk away, and fade into fog. They are off until you turn them on. Snow faces you so it stays visible when you turn. Rain stays upright so it reads as streaks.
What to ask for
- Rain or snow in the sandbox (or both)
What not to ask for
- A GPU weather compute system or accumulation on the ground (not this module)
- Points or tiny boxes for snow — they vanish edge-on. Use the existing flakes
Prompt examples
Use NGIN weather. Turn snow on. Do not write a new weather system.
Try it in the sandbox. Walking APIs: docs/walking-module.md. Actions / carry / inventory APIs: docs/interaction-module.md. Vehicles / towing: docs/vehicle-module.md. GLB: docs/glb-module.md. PBR: docs/pbr-module.md. Water / boats: docs/water-module.md. Lighting / day-night / particles / weather: docs/effects-module.md.