@opengamehq/cli 0.0.0-stage → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +238 -0
- package/CHANGELOG.md +22 -0
- package/README.md +129 -2
- package/dist/cli.mjs +1432 -0
- package/dist/opengame-global.js +49 -0
- package/dist/opengame-global.js.LEGAL.txt +1 -0
- package/dist/preflight-worker.mjs +20 -0
- package/dist/runtime-builder.mjs +800 -0
- package/dist/runtime-catalog.json +1 -0
- package/dist/runtime-catalog.sha256 +1 -0
- package/dist/runtime-shells/runtime-shell.html +4 -0
- package/dist/runtime-shells/runtime-shell.js +91 -0
- package/dist/safe-fs.py +242 -0
- package/dist/skills/manifest.json +516 -0
- package/dist/skills/opengame-accessibility/SKILL.md +90 -0
- package/dist/skills/opengame-api/SKILL.md +85 -0
- package/dist/skills/opengame-assets/SKILL.md +124 -0
- package/dist/skills/opengame-assets/references/pipeline.md +97 -0
- package/dist/skills/opengame-audio/SKILL.md +154 -0
- package/dist/skills/opengame-audio/helpers/audio-chain.js +325 -0
- package/dist/skills/opengame-audio/references/mix-notes.md +82 -0
- package/dist/skills/opengame-capture/SKILL.md +108 -0
- package/dist/skills/opengame-capture/references/pipeline.md +82 -0
- package/dist/skills/opengame-capture/references/threejs.md +145 -0
- package/dist/skills/opengame-characters/SKILL.md +129 -0
- package/dist/skills/opengame-characters/references/integration.md +144 -0
- package/dist/skills/opengame-characters/references/player-og.md +160 -0
- package/dist/skills/opengame-cli/SKILL.md +118 -0
- package/dist/skills/opengame-deploy/SKILL.md +207 -0
- package/dist/skills/opengame-deploy/references/json-events.md +62 -0
- package/dist/skills/opengame-deploy/references/manifest.md +83 -0
- package/dist/skills/opengame-deploy/references/packaging.md +117 -0
- package/dist/skills/opengame-depth/SKILL.md +130 -0
- package/dist/skills/opengame-enemies/SKILL.md +103 -0
- package/dist/skills/opengame-enemies/references/threejs.md +134 -0
- package/dist/skills/opengame-front-end/SKILL.md +143 -0
- package/dist/skills/opengame-front-end/references/launch.md +50 -0
- package/dist/skills/opengame-front-end/references/menus.md +47 -0
- package/dist/skills/opengame-game-feel/SKILL.md +137 -0
- package/dist/skills/opengame-game-feel/helpers/spring.js +146 -0
- package/dist/skills/opengame-game-feel/references/feel-numbers.md +83 -0
- package/dist/skills/opengame-jam/SKILL.md +103 -0
- package/dist/skills/opengame-lighting/SKILL.md +94 -0
- package/dist/skills/opengame-lighting/helpers/light-pool.js +185 -0
- package/dist/skills/opengame-loading/SKILL.md +99 -0
- package/dist/skills/opengame-loading/references/threejs.md +116 -0
- package/dist/skills/opengame-look/SKILL.md +114 -0
- package/dist/skills/opengame-look/references/post-and-lens.md +66 -0
- package/dist/skills/opengame-mobile/SKILL.md +90 -0
- package/dist/skills/opengame-performance/SKILL.md +140 -0
- package/dist/skills/opengame-performance/references/measuring.md +72 -0
- package/dist/skills/opengame-production/SKILL.md +131 -0
- package/dist/skills/opengame-production/references/templates.md +63 -0
- package/dist/skills/opengame-quality-bar/SKILL.md +122 -0
- package/dist/skills/opengame-quality-bar/references/cheap-tells.md +36 -0
- package/dist/skills/opengame-quality-bar/references/review-prompt.md +27 -0
- package/dist/skills/opengame-router/SKILL.md +51 -0
- package/dist/skills/opengame-router/references/process.md +38 -0
- package/dist/skills/opengame-scene-audit/SKILL.md +123 -0
- package/dist/skills/opengame-scene-audit/helpers/scene-audit.js +599 -0
- package/dist/skills/opengame-sdk/SKILL.md +270 -0
- package/dist/skills/opengame-sdk/references/engines.md +93 -0
- package/dist/skills/opengame-sdk/references/frame.md +107 -0
- package/dist/skills/opengame-sdk/references/identity.md +112 -0
- package/dist/skills/opengame-sdk/references/leaderboards.md +105 -0
- package/dist/skills/opengame-sdk/references/radio.md +71 -0
- package/dist/skills/opengame-stability/SKILL.md +84 -0
- package/dist/skills/opengame-verification/SKILL.md +136 -0
- package/dist/skills/opengame-verification/helpers/browser-evidence.mjs +74 -0
- package/dist/skills/opengame-weapons/SKILL.md +109 -0
- package/dist/skills/opengame-weapons/references/handling-numbers.md +72 -0
- package/dist/skills/opengame-weapons/references/threejs.md +169 -0
- package/dist/skills/opengame-world-physics/SKILL.md +114 -0
- package/dist/skills/opengame-world-physics/references/measured-failures.md +52 -0
- package/package.json +38 -4
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# Menus in practice
|
|
2
|
+
|
|
3
|
+
## Interface sound
|
|
4
|
+
|
|
5
|
+
- Quiet, recorded, matched to the game's world, on hover, focus and click, with keyboard
|
|
6
|
+
focus sounding like hover. AAA bar values: hover at 0.34, click at 0.26 of the
|
|
7
|
+
interface bus.
|
|
8
|
+
- Debounce rapid navigation; never stack a hover and a focus cue for one action.
|
|
9
|
+
- On a fresh profile the menu mix starts at 30% and never exceeds it, including when
|
|
10
|
+
restoring saved settings; a saved lower level, including zero, is preserved (ST).
|
|
11
|
+
- Mute applies to every interface cue and every menu film without changing the saved
|
|
12
|
+
level. Unlock audio from the player's gesture, and handle a refused play without
|
|
13
|
+
blocking the controls.
|
|
14
|
+
- A menu film's own soundtrack is the menu ambience. Never layer a second music bed under
|
|
15
|
+
it, and stop conflicting beds when moving between menu and play.
|
|
16
|
+
|
|
17
|
+
## Controls and the controls legend
|
|
18
|
+
|
|
19
|
+
- One action table drives input handling, HUD hints, menu help and playtests, so a legend
|
|
20
|
+
can never disagree with the keys.
|
|
21
|
+
- Desktop shooter defaults (ST): WASD to move, mouse to look, left click to fire, right
|
|
22
|
+
click to hold aim and E to toggle it, Space to jump, Shift to sprint, C to crouch, F to
|
|
23
|
+
interact, R to reload, Q to cycle weapons, number keys for weapon slots, Escape to pause.
|
|
24
|
+
Use the bindings for mechanics the game has; genre conventions and the creator's choices
|
|
25
|
+
win.
|
|
26
|
+
- Holding aim still allows firing. Track mouse buttons with per-button events or the
|
|
27
|
+
buttons bitmask; `pointerdown` alone misses a second button pressed while one is held.
|
|
28
|
+
- Clear held keys and aim on pause, blur, death and restart. Ignore key repeat and text
|
|
29
|
+
fields.
|
|
30
|
+
- Every control is remappable (see `opengame-accessibility`).
|
|
31
|
+
|
|
32
|
+
## Pause
|
|
33
|
+
|
|
34
|
+
Solo pause stops simulation, enemies, scoring and timers together. Resume explicitly
|
|
35
|
+
with a fresh time baseline. A pointer-lock refusal lands on a usable menu. Safari and
|
|
36
|
+
Firefox spend Escape on leaving fullscreen, so pause cannot depend on Escape alone.
|
|
37
|
+
|
|
38
|
+
## Reflow
|
|
39
|
+
|
|
40
|
+
Menus reflow at narrow widths and at 200% zoom without clipped actions or horizontal
|
|
41
|
+
scrolling, and touch targets are comfortably sized. Responsive menus do not make a game
|
|
42
|
+
playable by touch; say so if it is not.
|
|
43
|
+
|
|
44
|
+
## Credits
|
|
45
|
+
|
|
46
|
+
When a shipped file's licence asks for attribution, the menu has a Credits or About
|
|
47
|
+
screen that shows it.
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: opengame-game-feel
|
|
3
|
+
description: Make a browser game feel responsive and weighty. Covers hit and kill feedback on the hit frame, hits on the player that read light or heavy, one game clock for hitstop and slow motion, camera sway that never moves the aim, third-person jitter, input that is never dropped, effects capped near the lens, springs, recoil, shake and the view model pass. Use when the person says it feels floaty, stiff or unresponsive, hits do not land, the camera or body jitters, effects freeze, or add juice.
|
|
4
|
+
metadata:
|
|
5
|
+
version: "1.0.0"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Game feel
|
|
9
|
+
|
|
10
|
+
Feel is a set of small, measurable responses attached to real events: the camera
|
|
11
|
+
answers a shot, the world answers a hit, the simulation pauses for a kill. Each one is
|
|
12
|
+
cheap, and each one has a way to go wrong that players feel before they can name it.
|
|
13
|
+
|
|
14
|
+
Rules carry five tags; `opengame-quality-bar` explains them and the game codes.
|
|
15
|
+
[helpers/spring.js](helpers/spring.js) holds the spring, trauma shake and hitstop; its
|
|
16
|
+
`selfTest()` plants the Euler spring this replaces and proves it is caught. Gun handling,
|
|
17
|
+
view model size, reloads and kill reactions per weapon are in `opengame-weapons`.
|
|
18
|
+
|
|
19
|
+
## Rules
|
|
20
|
+
|
|
21
|
+
### Find the layer that jitters before fixing anything
|
|
22
|
+
- **Invariant:** In a third-person or follow view, the character, the camera and the world move smoothly when running, walking, strafing, stopping and standing still, and when something jitters the team proves which of the three moves before changing any of them.
|
|
23
|
+
- **Technique:** Measure each layer on its own: camera position second difference, the body's screen position per frame, and changed pixels with the camera still. Simulate on a fixed step and interpolate the render. Ease the follow camera with an exponential, `1 - exp(-k * dt)`. Pull the spring arm in quickly on collision, hold the closest distance briefly, and let it out slowly. Gait clip choice and pose weights belong to `opengame-characters`.
|
|
24
|
+
- **Reference configuration:** OC "fixed" the camera and then the world before the owner said "the character/OGs body is the thing jittering". The cause was a gait clip picked from raw speed, and an 80 ms ease ended it, 3.5 days and 6 or more asks after the first report. The stop jump fell from 6.6 to 2.5 px and the strafe jump from 3.1 to 1.0 px. OC's spring arm pulls in over 25 to 75 ms and holds the closest distance for 0.3 s; a side collision had snapped it up to 1.15 m. Framing: over the shoulder 2.6 m back and 1.15 m right, wide 4.8 m back and 2.0 m right, aiming 2.2 m back, with the character's centroid at most 0.30 of the frame width from the left edge. An earlier OC session noted jitter "judged by looking at screenshots and low-frame-rate recordings ... Nobody ever measured it".
|
|
25
|
+
- **Applies when:** Every game with a follow camera. First-person games run the same camera checks on the view model.
|
|
26
|
+
- **Verify:** Record at the display rate while running, stopping, strafing along a wall and idling. Plot the body's screen position and the camera's second difference per frame; neither shows single-frame spikes, and an idle character's legs do not move.
|
|
27
|
+
|
|
28
|
+
### Hits on the player read light or heavy at a glance
|
|
29
|
+
- **Invariant:** A player who takes a hit knows how hard it was and where it came from on the next frame, the centre of the screen stays clear, and reduced motion keeps every cue while dropping the motion.
|
|
30
|
+
- **Technique:** Score severity per attacker and scale every response by it instead of firing one maximum response. Kick the view away from the attacker, never a random shake. Draw an edge arc toward the attacker and claw marks at the screen edge only. Add a heartbeat and desaturation as health falls. Run combat before the camera in the frame so the flinch is not a frame late.
|
|
31
|
+
- **Reference configuration:** OC passes a heavy hit when at least 6% of the screen changes by 25 or more levels within 0.1 s; an 80 ms flash was "too timid". Severity runs from 0.3 to 1.0 across the four enemy types; before that, every hit maxed out at about 28 damage on a 250 HP player. Edge arcs are 19 to 38 px at 1080p and fade over 0.7 to 0.9 s. Claws stay in the outer 18%, one per side, stack to three, tear in over 90 ms and dry to brown over 1.5 to 2 s. The low-health vignette stays in the outer 0.15 of the width at 35% opacity or less (it had covered 45% of the frame). Reduced motion caps hitstop at 40 ms and turns the kick off. OC's camera ran before combat, so the flinch landed a frame late.
|
|
32
|
+
- **Applies when:** Games where the player takes damage from directions.
|
|
33
|
+
- **Verify:** Take a light hit and a heavy hit from each side and capture the next six frames: the two read differently, each points at the attacker, and a centre box is unchanged.
|
|
34
|
+
|
|
35
|
+
### Hit and kill confirmation lands on the hit frame, once per enemy
|
|
36
|
+
- **Invariant:** The hit marker, confirm sound, enemy flinch and blood or sparks appear on the frame the hit resolves; hits, headshots and kills each have their own marker; each enemy shows one counting score pop; the crosshair never changes colour to report what it is over.
|
|
37
|
+
- **Technique:** Drive every confirmation from the resolved damage event. Keep one marker per hit type with its own lifetime, merge score pops per enemy into one counting number, and give flesh blood and metal sparks.
|
|
38
|
+
- **Reference configuration:** OC markers last 130, 165 and 240 ms for hit, headshot and kill, with a 500 ms headshot-kill marker, a cyan X for a hit and an off-white X for a kill. Score pops merge within 0.15 to 0.25 s in three rows 30 px apart. The enemy flinch peaks one frame after the hit and recovers in about 150 ms. Blood is 24 droplets at 2 to 5 m/s with a #5a1212 mist. The fire cue reaches a quarter of its peak within 3 ms. OC's crosshair had turned red whenever it was over the boss and was changed to never turn red.
|
|
39
|
+
- **Applies when:** Shooters, brawlers and any game where the player hits things.
|
|
40
|
+
- **Verify:** Fire a burst into one enemy and step the recording frame by frame: marker, sound and flinch share the hit frame, and one pop counts up.
|
|
41
|
+
|
|
42
|
+
### One game clock for hitstop and slow motion
|
|
43
|
+
- **Invariant:** Every timer that should slow with the game reads one time scale, hitstop and slow motion are measured in game time, effects keep moving through a hitstop, and a cinematic can switch hitstop off.
|
|
44
|
+
- **Technique:** Keep one clock object that hands out a scaled delta for the simulation and an unscaled delta for UI and anything meant to ignore slow motion, and make each subsystem choose one. Search the code for raw frame delta and frame counters in gameplay timers, effect emitters and physics steps. Slow actors and bosses by scaling their own delta, never by freezing them. Test every effect at a quarter speed.
|
|
45
|
+
- **Reference configuration:** OC's kill hitstop and melee holds ran on raw frame delta, so in slow motion they held runs of near-frozen frames, and the owner saw "frozen flips" in a film take after an audit had predicted the defect. A global hitstop froze the boss's clips and springs while targets kept moving, and the boss read as "jagged". A hitstop that held the effect clock froze shot flashes on screen ("why do the gun bullets and juice like just freeze"), which OC logged as a P0. The frame counts at quarter speed, and what each timer did under a capture step, are in `opengame-capture`.
|
|
46
|
+
- **Applies when:** Any game with hitstop, slow motion, kill cams or capture for trailers.
|
|
47
|
+
- **Verify:** Kill the same enemy at full speed and at 0.25x and record both: the hold lasts the same game time, effects and UI keep moving through it, and no effect strobes.
|
|
48
|
+
|
|
49
|
+
### Hitstop pauses the simulation, never the render
|
|
50
|
+
- **Invariant:** On a kill or a heavy hit, the simulation holds for a moment while rendering and input keep running, and repeated hitstops never stack into stutter.
|
|
51
|
+
- **Technique:** Return a reduced simulation step from a hitstop object (`createHitstop` in the helper) and render as normal. A freeze that ends mid-frame hands back the remainder. Rate-cap it, and keep it for heavy moments rather than every kill.
|
|
52
|
+
- **Reference configuration:** The ST starter holds 45 ms on a kill and 60 ms on a heavy hit; 30 to 60 ms is the useful range. None of DK, MC, AW or SR has hitstop, and each would gain from it. OC slowed play to 8% speed for 45 ms on a kill and 30 ms on a headshot, 100 ms on a downing blow and 40 to 60 ms on melee (an axe went from 75 to 60). Before a cap of once per 0.6 s it added up to 225 ms of freeze per second, which read as hitching, and OC ended with no hitstop on ordinary gun kills.
|
|
53
|
+
- **Applies when:** Melee, brawlers, shooters with kill beats. Not in precision platforming, where a pause eats an input window.
|
|
54
|
+
- **Verify:** Log simulated time and rendered frames through a kill: frames keep coming, simulated time stalls for the hold, and the mouse still turns the view. Kill a crowd in one burst and count the holds per second.
|
|
55
|
+
|
|
56
|
+
### Camera motion sells movement but never moves the aim
|
|
57
|
+
- **Invariant:** Sway, bob, flinch, landing jolts and FOV kicks make movement felt, while the shot always goes where the unshaken view points, aimed views stay calm, and the player can turn shake and blur down.
|
|
58
|
+
- **Technique:** Put sway and kick on a child of the aiming camera and cast shots from the parent. Kick the FOV per weapon class. Remove sway and bob while aiming. Blur the world with motion blur and keep the held weapon sharp. Offer an FOV slider and a shake setting.
|
|
59
|
+
- **Reference configuration:** OC: sprint sway 1.6 to 1.8 degrees per two steps, bob 0.4 to 0.8 degrees, walk 0.2 degrees; a heavy flinch of 3.9 degrees is back at rest in 0.12 s; the flinch spring is pitch 0.026, yaw 0.018, roll 0.055 rad at 7 Hz and damping 0.5. FOV kicks are 2.0 degrees for a shotgun, 2.4 for a launcher, 1.6 for a sniper and 0.2 for an SMG; landing jolts scale over 3 to 15 m/s of fall speed. Motion blur is on by default with the gun sharp, and the FOV slider runs 80 to 120. Sway and bob while aimed was "a big regression" in the owner's words.
|
|
60
|
+
- **Applies when:** First-person and over-the-shoulder shooters.
|
|
61
|
+
- **Verify:** Sprint and fire at a fixed target with sway on and then off; the spread on the target is the same. Aim and stand still; the view does not move.
|
|
62
|
+
|
|
63
|
+
### No input is ever dropped
|
|
64
|
+
- **Invariant:** Every press registers, the action starts on the frame of the input, a press made slightly early is buffered rather than lost, and releases are heard wherever the pointer is.
|
|
65
|
+
- **Technique:** Buffer jump and fire presses for a short window and replay them when they become legal. Let fire and reload run while sprinting. Listen for releases on the window, not the canvas, and handle cancel events so nothing stays pressed. Latch a held confirm key until it is released so it does not advance several menus. Request pointer lock inside the gesture that starts play.
|
|
66
|
+
- **Reference configuration:** OC buffers jump for 140 ms, so a press in the last 140 ms of a fall jumps on landing, and the air jump refills only on ground contact. Build placement lands on the click frame. The menu-click case, where releases outside the canvas were lost, is in `opengame-front-end`. A held Enter kept moving the owner through menus until it got a release latch.
|
|
67
|
+
- **Applies when:** Every game with real-time input.
|
|
68
|
+
- **Verify:** Record input and frames together: tap jump just before landing, release the mouse outside the window, hold Enter on a menu. Each press acts once, on the next frame.
|
|
69
|
+
|
|
70
|
+
### Effects near the lens are capped
|
|
71
|
+
- **Invariant:** No muzzle flash, explosion, glow or particle covers more than a small share of the frame or whites it out, however close to the camera it happens, and every shot shows a flash, a tracer, brass and an impact.
|
|
72
|
+
- **Technique:** Scale effects by distance to the camera, clamp HDR values before tonemapping, cull or fade particles near the lens, keep the flash short and warm, and draw tracers with a pixel floor so they never go sub-pixel.
|
|
73
|
+
- **Reference configuration:** OC: a wonder-weapon flash at HDR 10 within 1 m whited out the screen, and a 2.1 m crescent at 1.45 m filled 80% of the frame. The flash lasts 40 to 60 ms (two frames) and stays under 2% of the frame; the third-person flash is 1.9x (2.6x was too big); tracer cores are at least 3.2 px. One fix overshot the flash to 42% of its size, read as "hard to see", and settled at two thirds.
|
|
74
|
+
- **Applies when:** Games with flashes, explosions or bright effects near the player.
|
|
75
|
+
- **Verify:** Trigger each effect at 1, 3 and 10 m from the camera and count the pixels above 0.95; the share stays under the game's cap at every distance.
|
|
76
|
+
|
|
77
|
+
### Springs that cannot explode
|
|
78
|
+
- **Invariant:** Every spring-driven camera or view-model motion settles to rest at any frame time the game can produce, and lands in the same place at any frame rate.
|
|
79
|
+
- **Technique:** Solve the critically damped spring in closed form (`spring` in the helper) instead of integrating it step by step. Frame-rate independent easing toward a target uses `damp`, an exponential, never a fixed fraction per frame.
|
|
80
|
+
- **Reference configuration:** DK's recoil spring at omega 22, integrated explicitly, went unstable below about 44 fps and spun the camera. The helper's self-test shows a semi-implicit Euler spring at the same omega exploding at a 50 ms frame and drifting between 30 and 150 fps.
|
|
81
|
+
- **Applies when:** Any spring, follow camera, sway or smoothing.
|
|
82
|
+
- **Verify:** `springProperties(spring)` returns no failures, and the game survives a frame time pinned at its own clamp during heavy recoil.
|
|
83
|
+
|
|
84
|
+
### Recoil returns to the aim
|
|
85
|
+
- **Invariant:** After firing stops, the view returns to where the player was aiming, not to where recoil left it.
|
|
86
|
+
- **Technique:** Recoil is its own spring per axis, added on top of the aim and never written into it. Clamp each axis and drop the velocity into the clamp so the view does not bounce off the limit.
|
|
87
|
+
- **Reference configuration:** DK: omega 22 pitch, 20 yaw, 17 roll; clamps 0.11, 0.07, 0.09 rad. SR recoils the weapon only, with `exp(-24t) * cos(21t)` over 0.28 s, and shakes nothing. OC's per-class recoil springs are in `opengame-weapons`.
|
|
88
|
+
- **Applies when:** Shooters and any game with a kicking weapon or tool.
|
|
89
|
+
- **Verify:** Fire a burst at a fixed mark, stop, and wait half a second: the reticle is back on the mark.
|
|
90
|
+
|
|
91
|
+
### Shake is trauma squared, and it decays
|
|
92
|
+
- **Invariant:** Camera shake scales with how hard the event was, fades on its own, and never fights the player's aim.
|
|
93
|
+
- **Technique:** Events add trauma between zero and one; trauma decays linearly; the shake is trauma squared driving a few detuned sines per axis. Most of it is removed while aiming. Pick shake or weapon-only recoil for the game, not both.
|
|
94
|
+
- **Reference configuration:** DK: three sines per axis at 30 Hz, amplitudes 0.038 yaw, 0.032 pitch, 0.024 roll rad, decaying 1.6 per second; a shot adds 0.08, a heavy shot 0.22, a landing up to 0.35, an explosion up to 0.5; 25% kept while aiming. OC shakes for explosions out to 3.5 times their radius and has a shake setting.
|
|
95
|
+
- **Applies when:** Action games with impacts. Puzzle and calm games usually want none.
|
|
96
|
+
- **Verify:** After the largest event in the game, the view is still within a second.
|
|
97
|
+
|
|
98
|
+
### Bob follows the feet
|
|
99
|
+
- **Invariant:** Head bob and footsteps match distance travelled, so they keep pace with the feet at any speed and stop when the player stops.
|
|
100
|
+
- **Technique:** Advance a bob phase by distance walked over stride length, not by time, and fire footstep sounds on that phase.
|
|
101
|
+
- **Reference configuration:** DK: stride 1.35 m walking, 1.65 m sprinting, 0.95 m crouched; a 2:1 Lissajous at amplitude 0.042, cut by 86% while aiming. OC removes bob entirely while aiming.
|
|
102
|
+
- **Applies when:** First-person games on foot. Third-person games drive the same timing from the animation instead.
|
|
103
|
+
- **Verify:** Walk into a wall holding forward: the bob and the footsteps stop.
|
|
104
|
+
|
|
105
|
+
### The field of view answers speed
|
|
106
|
+
- **Invariant:** Speed is felt through the lens: sprinting and sliding widen the view, and it eases back faster than it widened.
|
|
107
|
+
- **Technique:** A held FOV kick eased with `damp`, a faster rate out than in, plus a short punch on entering a slide or dash.
|
|
108
|
+
- **Reference configuration:** DK: +9 degrees sprinting, in at rate 5.5 and out at 9; +6 sliding plus a 5 degree punch. SR widens 7 degrees with descent speed.
|
|
109
|
+
- **Applies when:** First-person and chase-camera games with speed changes.
|
|
110
|
+
- **Verify:** Record FOV per frame through a sprint start and stop; both are smooth curves with no step.
|
|
111
|
+
|
|
112
|
+
### The view model is its own pass
|
|
113
|
+
- **Invariant:** The player's weapon or hands render at a fixed lens with their own depth and light, never clipping into walls and never smeared by world effects.
|
|
114
|
+
- **Technique:** A separate camera and pass for the view model, after every depth-consuming world pass, at a fixed field of view and a tiny near plane, with its own small light rig and environment on its own layer. The three.js setup is in `opengame-weapons`.
|
|
115
|
+
- **Reference configuration:** DK: a 75 degree lens, near 0.012, a key of 1.34 and a cool rim of 0.44 on the view-model layer; the world's near plane moved out to 0.15 for a three times depth-precision gain. OC: world FOV 85 (65 to 110 on the slider), view model 75 degrees at near 0.012, pulling to 58.5 degrees when aimed; its studio environment gave 41% of the gun's brightness and the two directional lights about 3 luma.
|
|
116
|
+
- **Applies when:** First-person games with a visible weapon or tool.
|
|
117
|
+
- **Verify:** Press the view model into a wall and sweep the FOV slider; the weapon neither clips nor changes size.
|
|
118
|
+
|
|
119
|
+
### Every surface answers a hit
|
|
120
|
+
- **Invariant:** An impact looks and sounds like the material it hit, and its mark outlasts its dust.
|
|
121
|
+
- **Technique:** A per-surface table (dust, chips, sparks, decal colour and size, sound family, light flash) looked up by the hit surface. Decals live in a fixed ring so the oldest goes first.
|
|
122
|
+
- **Reference configuration:** DK: metal throws 9 sparks and concrete none, a 0.35 light flash on metal, a ring of 64 decals oriented to the surface, holes living 40 s and fading over their last fifth.
|
|
123
|
+
- **Applies when:** Any game where things are hit.
|
|
124
|
+
- **Verify:** Shoot or strike each surface type once and capture the next second; each reads differently.
|
|
125
|
+
|
|
126
|
+
### One complete feedback set per action, and input never waits
|
|
127
|
+
- **Invariant:** Each player action has anticipation, impact, sound, camera response and a trace that lingers, all driven by the resolved outcome, and no animation ever delays the input that started it.
|
|
128
|
+
- **Technique:** Drive hit, shield-break and kill feedback from resolved damage events, not from the attack button. Stack a kill on several channels: marker, protected sound, score popup, a voice or callout. Start the action on the input frame and let presentation catch up.
|
|
129
|
+
- **Reference configuration:** MC and AW stack kill confirmation on four channels. ST's craft defaults: never delay input for an animation, and keep a stable cue for reduced motion.
|
|
130
|
+
- **Applies when:** Every game.
|
|
131
|
+
- **Verify:** Measure input to first visible response with a frame recording; it is the next frame. Kill something and list every channel that answered.
|
|
132
|
+
|
|
133
|
+
## More numbers
|
|
134
|
+
|
|
135
|
+
Muzzle flashes, explosions scaled by radius, loot that lands, third-person camera values
|
|
136
|
+
from SR and OC, and OC's player-damage and confirmation tables are in
|
|
137
|
+
[references/feel-numbers.md](references/feel-numbers.md).
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Camera and hit-feel primitives that stay correct at any frame time. Copy this file
|
|
3
|
+
* into the game; it imports nothing and touches no scene object. Each piece returns
|
|
4
|
+
* numbers the game adds to its camera or its simulation step, so aim, collision and
|
|
5
|
+
* where a shot goes stay the game's own truth.
|
|
6
|
+
*
|
|
7
|
+
* import { spring, damp, createTrauma, createHitstop, selfTest } from "./spring.js";
|
|
8
|
+
*
|
|
9
|
+
* const recoil = { x: 0, v: 0 }; // one per axis
|
|
10
|
+
* recoil.v += kick; // on a shot
|
|
11
|
+
* camera.rotation.x += spring(recoil, 0, 22, dt);
|
|
12
|
+
*
|
|
13
|
+
* const shake = createTrauma(); // shake.add(0.3) on an impact
|
|
14
|
+
* const o = shake.update(dt, { aiming }); // o.yaw, o.pitch, o.roll in radians
|
|
15
|
+
*
|
|
16
|
+
* const stop = createHitstop(); // stop.hold(0.05) on a kill
|
|
17
|
+
* const simDt = stop.step(dt); // simulate with simDt, render with dt
|
|
18
|
+
*
|
|
19
|
+
* Run `selfTest()` once after editing this file. It plants the integrator this file
|
|
20
|
+
* exists to replace and fails unless that planted version is caught.
|
|
21
|
+
*/
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* A critically damped spring, solved in closed form. `state` is `{ x, v }` and is
|
|
25
|
+
* updated in place; the new position is returned. Exact for a constant target, so the
|
|
26
|
+
* result after one second is the same at 30 fps, 144 fps or one 50 ms hitch.
|
|
27
|
+
* `omega` is the angular frequency in radians per second: higher is stiffer.
|
|
28
|
+
*/
|
|
29
|
+
export function spring(state, target, omega, dt) {
|
|
30
|
+
const d = state.x - target;
|
|
31
|
+
const e = Math.exp(-omega * dt);
|
|
32
|
+
const c = state.v + omega * d;
|
|
33
|
+
state.x = target + (d + c * dt) * e;
|
|
34
|
+
state.v = (state.v - c * omega * dt) * e;
|
|
35
|
+
return state.x;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/** Frame-rate independent approach toward a target, for FOV kicks and blends. */
|
|
39
|
+
export function damp(current, target, rate, dt) {
|
|
40
|
+
return target + (current - target) * Math.exp(-rate * dt);
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* Trauma-squared shake. Events add trauma between 0 and 1; trauma decays linearly;
|
|
45
|
+
* the shake is trauma squared, so small hits barely move the view and big ones do.
|
|
46
|
+
* Three detuned sines per axis read as noise without allocating or seeding anything.
|
|
47
|
+
* Defaults are Der Koloss's reference configuration; tune per game.
|
|
48
|
+
*/
|
|
49
|
+
export const TRAUMA_DEFAULTS = Object.freeze({
|
|
50
|
+
decayPerSecond: 1.6, hz: 30, amplitude: { yaw: 0.038, pitch: 0.032, roll: 0.024 }, aimingKeeps: 0.25,
|
|
51
|
+
});
|
|
52
|
+
|
|
53
|
+
export function createTrauma(tuning = TRAUMA_DEFAULTS) {
|
|
54
|
+
let trauma = 0, t = 0;
|
|
55
|
+
return {
|
|
56
|
+
add(amount) { trauma = Math.min(1, trauma + Math.max(0, amount)); },
|
|
57
|
+
get trauma() { return trauma; },
|
|
58
|
+
update(dt, { aiming = false } = {}) {
|
|
59
|
+
trauma = Math.max(0, trauma - dt * tuning.decayPerSecond);
|
|
60
|
+
t += dt * tuning.hz;
|
|
61
|
+
const s = trauma * trauma * (aiming ? tuning.aimingKeeps : 1);
|
|
62
|
+
return {
|
|
63
|
+
yaw: (Math.sin(t * 1.3) * 0.6 + Math.sin(t * 3.7) * 0.4) * tuning.amplitude.yaw * s,
|
|
64
|
+
pitch: (Math.cos(t * 1.7) * 0.6 + Math.cos(t * 4.3) * 0.4) * tuning.amplitude.pitch * s,
|
|
65
|
+
roll: (Math.sin(t * 2.3) * 0.6 + Math.sin(t * 5.1) * 0.4) * tuning.amplitude.roll * s,
|
|
66
|
+
};
|
|
67
|
+
},
|
|
68
|
+
};
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* Hitstop: a short freeze of the SIMULATION on a kill or a heavy hit. The render loop
|
|
73
|
+
* and input keep running, so the frame holds while the game still answers the mouse.
|
|
74
|
+
* `step(dt)` returns the time the simulation should advance this frame; a freeze that
|
|
75
|
+
* ends part-way through a frame hands back the remainder rather than swallowing it.
|
|
76
|
+
*/
|
|
77
|
+
export function createHitstop() {
|
|
78
|
+
let remaining = 0;
|
|
79
|
+
return {
|
|
80
|
+
hold(seconds) { remaining = Math.max(remaining, seconds); },
|
|
81
|
+
get frozen() { return remaining > 0; },
|
|
82
|
+
step(dt) {
|
|
83
|
+
if (remaining <= 0) return dt;
|
|
84
|
+
const spent = Math.min(remaining, dt);
|
|
85
|
+
remaining -= spent;
|
|
86
|
+
return dt - spent;
|
|
87
|
+
},
|
|
88
|
+
};
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/** The integrator this file replaces: semi-implicit Euler on the same spring. */
|
|
92
|
+
function eulerSpring(state, target, omega, dt) {
|
|
93
|
+
const a = -omega * omega * (state.x - target) - 2 * omega * state.v;
|
|
94
|
+
state.v += a * dt;
|
|
95
|
+
state.x += state.v * dt;
|
|
96
|
+
return state.x;
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/** Runs a spring from a recoil kick for `seconds` at a fixed `dt`. */
|
|
100
|
+
function settle(step, omega, dt, seconds) {
|
|
101
|
+
const state = { x: 0, v: 1 };
|
|
102
|
+
let peak = 0;
|
|
103
|
+
for (let time = 0; time < seconds - 1e-9; time += dt) peak = Math.max(peak, Math.abs(step(state, 0, omega, dt)));
|
|
104
|
+
return { final: Math.abs(state.x), peak };
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
/**
|
|
108
|
+
* The two properties the game relies on, measured against `step`:
|
|
109
|
+
* - stable: a recoil kick returns to rest within a second, even at a 50 ms frame;
|
|
110
|
+
* - frame-rate independent: the pose after half a second is the same at 30 and 144 fps.
|
|
111
|
+
* Returns a list of failures; empty means the properties hold.
|
|
112
|
+
*/
|
|
113
|
+
export function springProperties(step, omega = 22) {
|
|
114
|
+
const failures = [];
|
|
115
|
+
for (const dt of [1 / 144, 1 / 60, 1 / 30, 1 / 20]) {
|
|
116
|
+
const { final, peak } = settle(step, omega, dt, 1);
|
|
117
|
+
if (!(final < 1e-3) || !(peak < 1)) failures.push(`unstable at ${Math.round(1 / dt)} fps: final ${final.toExponential(2)}, peak ${peak.toFixed(3)}`);
|
|
118
|
+
}
|
|
119
|
+
const slow = settle(step, omega, 1 / 30, 0.5).final, fast = settle(step, omega, 1 / 150, 0.5).final;
|
|
120
|
+
if (Math.abs(slow - fast) > 1e-6) failures.push(`frame-rate dependent: ${slow.toExponential(3)} at 30 fps, ${fast.toExponential(3)} at 150 fps`);
|
|
121
|
+
return failures;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* Plants the Euler spring first and requires the properties to catch it, then checks
|
|
126
|
+
* this file's spring, trauma and hitstop. Returns `{ ok, examined, failures }`.
|
|
127
|
+
*/
|
|
128
|
+
export function selfTest() {
|
|
129
|
+
const failures = [];
|
|
130
|
+
let examined = 0;
|
|
131
|
+
const planted = springProperties(eulerSpring); examined++;
|
|
132
|
+
if (!planted.length) failures.push("planted Euler spring was not caught; the property check is broken");
|
|
133
|
+
const real = springProperties(spring); examined++;
|
|
134
|
+
failures.push(...real.map((f) => `spring: ${f}`));
|
|
135
|
+
|
|
136
|
+
const shake = createTrauma(); shake.add(1); examined++;
|
|
137
|
+
let last = 0;
|
|
138
|
+
for (let i = 0; i < 120; i++) last = Math.abs(shake.update(1 / 60).yaw);
|
|
139
|
+
if (shake.trauma > 0 || last !== 0) failures.push("trauma was still shaking the view two seconds after a full hit");
|
|
140
|
+
|
|
141
|
+
const stop = createHitstop(); stop.hold(0.05); examined++;
|
|
142
|
+
let simulated = 0;
|
|
143
|
+
for (let i = 0; i < 6; i++) simulated += stop.step(1 / 60);
|
|
144
|
+
if (Math.abs(simulated - (6 / 60 - 0.05)) > 1e-9) failures.push(`hitstop simulated ${simulated.toFixed(4)} s of 0.05 s after a 0.05 s hold`);
|
|
145
|
+
return { ok: failures.length === 0, examined, failures };
|
|
146
|
+
}
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# Feel numbers from our games
|
|
2
|
+
|
|
3
|
+
Reference configurations, each from the game named. Use them as a starting point for a
|
|
4
|
+
game of the same kind and scale, then tune by feel with frame recordings.
|
|
5
|
+
|
|
6
|
+
## Muzzle flash and shots (DK, MC)
|
|
7
|
+
|
|
8
|
+
- A 45 to 58 ms HDR core, a few streaks, one wisp of smoke that builds into a haze under
|
|
9
|
+
sustained fire, and a 55 ms point light from the light pool.
|
|
10
|
+
- Each shot adds 0.07 of exposure flash (a heavy shot 0.16), decaying at 7 per second.
|
|
11
|
+
- Pad rumble where a gamepad is connected: a shot (0.08, 0.22, 45 ms), damage taken
|
|
12
|
+
(0.35, 0.15, 110 ms).
|
|
13
|
+
|
|
14
|
+
## Explosions, scaled by radius k (DK)
|
|
15
|
+
|
|
16
|
+
A 26k fireball, 22k bouncing embers, 20k smoke, a 16k ground ring, a 0.42 s light, and
|
|
17
|
+
trauma of 0.5k.
|
|
18
|
+
|
|
19
|
+
## Loot that lands (SR)
|
|
20
|
+
|
|
21
|
+
Items eject with a 0.085 s stagger on a 0.62 s ballistic arc at g = 14 with spin, settle
|
|
22
|
+
over 0.24 s, then hover at 0.34 m with a 0.055 m bob. Hover, spin and glow are
|
|
23
|
+
presentation only; the pickup position is where the item landed.
|
|
24
|
+
|
|
25
|
+
## Third-person camera (SR)
|
|
26
|
+
|
|
27
|
+
- Boom distance and shoulder offset from the character's height, not constants.
|
|
28
|
+
- Rotate the boom instantly on mouse input; ease only its length and obstruction with
|
|
29
|
+
`1 - exp(-14 dt)`.
|
|
30
|
+
- Pull 0.15 to 0.22 m inside a collision hit; stay 0.4 m above terrain.
|
|
31
|
+
- Smooth stair steps with a separate offset clamped to 0.35 m either way, so the camera
|
|
32
|
+
does not hop with every riser.
|
|
33
|
+
|
|
34
|
+
## Idle sway
|
|
35
|
+
|
|
36
|
+
Golden-ratio frequencies (1, 0.618, 0.382) so its loop is never seen, about 0.8 degrees
|
|
37
|
+
peak to peak (DK).
|
|
38
|
+
|
|
39
|
+
## Hit reactions on bodies (MC)
|
|
40
|
+
|
|
41
|
+
An additive layer of 0.34 s, `exp(-5p) * sin(2.2 pi p)` from the lower back to the head, signed by the
|
|
42
|
+
side that was hit. Directional deaths: dot the fatal shot against facing, plus or minus
|
|
43
|
+
0.35, and pick front, back, head or collapse.
|
|
44
|
+
|
|
45
|
+
## Callouts (MC)
|
|
46
|
+
|
|
47
|
+
Queued medals fade in over 0.22 s, hold 1.35 s, fade out over 0.45 s, stagger 0.55 s, at
|
|
48
|
+
most three visible.
|
|
49
|
+
|
|
50
|
+
## Hits on the player (OC)
|
|
51
|
+
|
|
52
|
+
- Severity per attacker type: 0.3, 0.5, 0.9 and 1.0 for OC's four zombie types, scaling
|
|
53
|
+
every response below.
|
|
54
|
+
- Directional kick instead of random shake; 45 ms hitstop on heavy hits, 100 ms on the
|
|
55
|
+
downing blow.
|
|
56
|
+
- Edge arcs 19 to 38 px at 1080p facing the attacker, fading over 0.7 to 0.9 s.
|
|
57
|
+
- Claws in the outer 18% of the screen, one per side, stacking to three, tearing in over
|
|
58
|
+
90 ms and drying to brown over 1.5 to 2 s.
|
|
59
|
+
- Desaturation, vignette and heartbeat as health drops; the vignette stays in the outer
|
|
60
|
+
0.15 of the width at 35% opacity or less.
|
|
61
|
+
- Reduced motion caps hitstop at 40 ms and disables the kick.
|
|
62
|
+
- Pass test: a heavy hit changes at least 6% of the screen by 25 or more levels within
|
|
63
|
+
0.1 s.
|
|
64
|
+
|
|
65
|
+
## Confirmation (OC)
|
|
66
|
+
|
|
67
|
+
- Markers: 130 ms hit, 165 ms headshot, 240 ms kill, 500 ms headshot kill. Cyan X for a
|
|
68
|
+
hit, off-white X for a kill. Hidden in camera views with no crosshair.
|
|
69
|
+
- Score pops merge per enemy within 0.15 to 0.25 s, in three rows 30 px apart.
|
|
70
|
+
- Enemy flinch: torso about 8 to 9 degrees, pelvis back 4 to 6 cm, peak within one frame,
|
|
71
|
+
recovery about 150 ms; a stagger only above 35% of max health in one hit (50% on the
|
|
72
|
+
heaviest type), 0.35 to 0.45 s with a 1.2 s cooldown, so big enemies never stun-lock.
|
|
73
|
+
- Blood: 24 droplets at 2 to 5 m/s, 5 cm streaks living 0.25 to 0.5 s, mist #5a1212.
|
|
74
|
+
|
|
75
|
+
## Third-person camera (OC)
|
|
76
|
+
|
|
77
|
+
- Over the shoulder 2.6 m back and 1.15 m right; wide 4.8 m back and 2.0 m right; aiming
|
|
78
|
+
pulls to 2.2 m. Exactly three views, with the same aim key in all of them.
|
|
79
|
+
- Downed camera high: 3.0 m back, 3.1 m up, about 43 degrees down.
|
|
80
|
+
- Spring arm pulls in over 25 to 75 ms and holds the closest distance 0.3 s.
|
|
81
|
+
- Objects within 0.65 m of the lens dither-fade, reaching 30% at 0.3 m.
|
|
82
|
+
- Jitter metrics: camera position second difference, body screen pixels per frame (stop
|
|
83
|
+
6.6 to 2.5 px after the fix), arm pops over 10 and 25 cm.
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: opengame-jam
|
|
3
|
+
description: Enter a game in an OpenGame jam. Finds the open jams, their tracks and rules, checks the game against them, and submits one exact release as an entry with the person's own answers, leaving the certification to the person. Use when the person says enter the jam, submit to the jam, which track should I pick, am I eligible, what are the jam rules, or mentions the OpenGame Global AI Game Jam.
|
|
4
|
+
metadata:
|
|
5
|
+
version: "1.0.6"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Enter an OpenGame jam
|
|
9
|
+
|
|
10
|
+
OpenGame opens on 17 November 2026. Jam entries open on 18 November and close on
|
|
11
|
+
18 December, 11:59 pm PT; after the close every deploy path answers `entries_closed`.
|
|
12
|
+
|
|
13
|
+
Until 18 November, entries stay closed: the CLI and the API answer
|
|
14
|
+
"OpenGame opens for creators on 18 November." to everybody outside the OpenGame team,
|
|
15
|
+
so no entry can be submitted. The game can still be made ready: build it, play it, and gather the answers below.
|
|
16
|
+
|
|
17
|
+
A jam is an extra destination for a game already on OpenGame. Games go to the
|
|
18
|
+
marketplace; a jam entry is one exact release submitted with the jam's answers,
|
|
19
|
+
reviewed, then judged by people. Deploy the game first: read `opengame-deploy` if the
|
|
20
|
+
game has no `releaseId` yet.
|
|
21
|
+
|
|
22
|
+
No jam is built into the CLI. Tracks, fields, rules and the certification text come
|
|
23
|
+
from the server, so the next jam needs no new CLI. Read them fresh each time; do
|
|
24
|
+
not answer from memory or from this file.
|
|
25
|
+
|
|
26
|
+
## Find the jam and its rules
|
|
27
|
+
|
|
28
|
+
1. `opengame jams --json` lists the jams with their slug, state, tracks and a rules link.
|
|
29
|
+
2. Read the rules page. Tell the person, in a sentence each, the rules their game might
|
|
30
|
+
break. Eligibility is theirs to decide.
|
|
31
|
+
|
|
32
|
+
## Check the game against the rules before submitting
|
|
33
|
+
|
|
34
|
+
The first jam's published rules, as an example of what to check (the server's copy is
|
|
35
|
+
the authority):
|
|
36
|
+
|
|
37
|
+
- **Made during the jam.** Started after kickoff. Earlier libraries and boilerplate
|
|
38
|
+
are fine; an earlier prototype of this game is not.
|
|
39
|
+
- **Exports a web build.** Any engine works if its web build (HTML5, WebGL, WebGPU
|
|
40
|
+
or WebAssembly) runs from static files. `opengame check` names the engine it detects
|
|
41
|
+
and reports the problems it can find before a deploy.
|
|
42
|
+
- **Runs in a desktop browser** with nothing to install, no account, no sign-in and no
|
|
43
|
+
email address, and responds to the window being resized.
|
|
44
|
+
- **May call out, within the platform rules.** At runtime the game may call AI models,
|
|
45
|
+
third-party APIs and its own servers, besides `https://api.opengame.gg` for
|
|
46
|
+
scores. It must still draw its first frame offline, because review runs without the
|
|
47
|
+
internet. Keys stay on the creator's server, never in the bundle.
|
|
48
|
+
- **Free to play, with no crypto, ads or tracking.** No payments, tips or donations, no
|
|
49
|
+
wallets or tokens, no ads or ad pixels, no session recording. `opengame-deploy` has
|
|
50
|
+
the full rules.
|
|
51
|
+
- **Inside the bundle limits:** 1024 MiB zipped,
|
|
52
|
+
1536 MiB unzipped, 10,000 files.
|
|
53
|
+
- **The person owns the art, audio, models, fonts and code**, or holds a licence to
|
|
54
|
+
ship them.
|
|
55
|
+
- **A game or a world, not a decomp or a mod.** Read `kind` in `opengame.json`. A decomp
|
|
56
|
+
or a mod is made from someone else's game, so it cannot meet the rules above.
|
|
57
|
+
`opengame submit` stops it, and the server returns `kind_not_in_jam`. It can still go
|
|
58
|
+
on OpenGame, but not into the jam. If the kind is wrong, fix it in `opengame.json` and
|
|
59
|
+
deploy again; do not change it only to get past this rule.
|
|
60
|
+
- **Individual creators, 18 or over, no teams**, up to
|
|
61
|
+
2 entries each.
|
|
62
|
+
|
|
63
|
+
If something looks like it breaks a rule, tell the person what and where, and let them
|
|
64
|
+
decide. Do not hide a dependency, rewrite history or relabel a library to pass a rule.
|
|
65
|
+
|
|
66
|
+
## Pick a track with the person
|
|
67
|
+
|
|
68
|
+
- **Genre track:** one per entry, required. The CLI suggests one from the game's
|
|
69
|
+
`genre` in `opengame.json`; the person confirms or changes it.
|
|
70
|
+
- **Sponsor tracks:** earned, not picked. The CLI offers a sponsor track only when the
|
|
71
|
+
person used a model from that sponsor. Each takes an optional evidence note of up to
|
|
72
|
+
2,000 characters about what the model did ("all 38 prop
|
|
73
|
+
textures and the menu film"). A reviewer checks it, so write only what is true and
|
|
74
|
+
what a reviewer can find in the game.
|
|
75
|
+
- **Models used** (`--models`) is the one other field. `opengame jams <slug> --json`
|
|
76
|
+
lists the whole form. Ask the person which models they used; do not guess from the
|
|
77
|
+
code.
|
|
78
|
+
|
|
79
|
+
## Deploy and submit
|
|
80
|
+
|
|
81
|
+
Follow `opengame-deploy` for the shared installation, sign-in, deploy and submission procedure. The server selects the destination for the current jam; fetch its fields with `opengame jams <slug> --json`. Use the exact release the creator played.
|
|
82
|
+
|
|
83
|
+
## What only the person can do
|
|
84
|
+
|
|
85
|
+
**Certification is the person's legal statement**, made in their browser under a
|
|
86
|
+
versioned set of terms. When the result asks for it, give the person the link and tell
|
|
87
|
+
them what it is for. Do not open it for them, click through it, or tell them it is
|
|
88
|
+
done. A later revision of the same entry under the same terms skips it.
|
|
89
|
+
|
|
90
|
+
The person also decides whether they are eligible (age, one account), whether they own
|
|
91
|
+
the assets, which track they want, and what their sponsor evidence claims.
|
|
92
|
+
|
|
93
|
+
## After submitting
|
|
94
|
+
|
|
95
|
+
`opengame status . --watch --json` follows review until it finishes or the watch
|
|
96
|
+
ends. The result's `review` has the state, `done`, and `next`, the command to run. A
|
|
97
|
+
returned entry's findings come as `finding` events, the same as a deploy's. Fix them,
|
|
98
|
+
deploy a new release, and submit that release. Review is automated first, then a
|
|
99
|
+
person; people judge the jam. Judges see the release that was submitted, so later
|
|
100
|
+
edits count only once a new release is submitted.
|
|
101
|
+
|
|
102
|
+
The jam's judging criteria are published on its rules page. Fun and craft carry the
|
|
103
|
+
most weight; the craft skills (`opengame-quality-bar` first) are how to raise them.
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: opengame-lighting
|
|
3
|
+
description: Light a three.js browser game so it reads as a place. Covers characters that do not read as black silhouettes, counting light sources against the renderer's light limit, one shadow key that does not crawl, a fixed pool of real lights, real indirect light, and effects lit by the scene. Use when the person says the lighting is flat, characters look black, shadows flicker, the game stutters when lights turn on, it is too dark, add lamps or torches, or particles look pasted on.
|
|
4
|
+
metadata:
|
|
5
|
+
version: "1.0.0"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Lighting
|
|
9
|
+
|
|
10
|
+
Most flat-looking games have one problem: everything is lit by an ambient term, so
|
|
11
|
+
nothing is darker than anything else. The fix is a costed rig: one real shadow-casting
|
|
12
|
+
key, a weak fill, real indirect light, and a fixed number of point lights however many
|
|
13
|
+
lamps the level has.
|
|
14
|
+
|
|
15
|
+
Rules carry five tags; `opengame-quality-bar` explains them and the game codes.
|
|
16
|
+
|
|
17
|
+
## Rules
|
|
18
|
+
|
|
19
|
+
### No character is a silhouette
|
|
20
|
+
- **Invariant:** Every character, creature and held item shows form and colour against every background it appears on, and none reads as a black silhouette.
|
|
21
|
+
- **Technique:** Light characters on purpose: an ambient or hemisphere term that reaches skinned materials, a rim from the side away from the key, and a fill so hands and faces keep detail in backlight. Confirm the character shader receives each term, because a fill that reads an empty input has no effect. Give the view model its own environment. In three.js add a `HemisphereLight`, a Fresnel rim through `onBeforeCompile` on the character's `MeshStandardMaterial`, and a PMREM environment on the view-model scene.
|
|
22
|
+
- **Reference configuration:** OC's first review found "black silhouettes with glowing balls stuck on them". The renderer gave skinned meshes no rim, fill or ambient, and the ambient term it did have read zero without a sky probe; fixing it took shader edits in 3 streams. The view model's studio environment gave 41% of the gun's brightness. OC keeps zombie flesh lighter than the floor (its albedo L was 17 against a target of 50 or more) and the boss at 2:1 contrast or better against its background (pit fog had cut it to 1.12:1).
|
|
23
|
+
- **Applies when:** Every 3D game with characters, dark scenes above all.
|
|
24
|
+
- **Verify:** Capture each character type in the darkest spot and the most backlit spot of each level, then sample face, hands and torso against the floor behind them.
|
|
25
|
+
|
|
26
|
+
### Count the light sources against the light limit on day one
|
|
27
|
+
- **Invariant:** Before anyone tunes the look, the team has counted the things that look like they emit light and measured the light limit the renderer applies, adaptive quality included.
|
|
28
|
+
- **Technique:** List every fire, lamp, screen and glow the concept implies and compare that count with the limit the renderer uses at runtime. Where sources outnumber lights, plan for it: bake static fire into lightmaps or probes, show the nearest sources through the pool below, and let emissive plus bloom carry the rest. Pin quality in captures so adaptive quality cannot drop lights unseen. In three.js `WebGLRenderer` shades every light for every lit fragment and recompiles when the light count changes, so route many sources through a pool.
|
|
29
|
+
- **Reference configuration:** OC's arena had 218 to 224 fire sites against a 32-light cap, and adaptive quality dropped captures to "8 of 224". The cap surfaced only after about 6 rejections on day one. 224 clustered lights measured about 0.2 ms, so raising the cap was cheap.
|
|
30
|
+
- **Applies when:** Any level lit by many practicals: fires, torches, neon, screens.
|
|
31
|
+
- **Verify:** Log the active light count each frame with quality pinned and unpinned. It matches the plan, and a walk past every fire shows no source going dark.
|
|
32
|
+
|
|
33
|
+
### One shadow-casting key that does not crawl
|
|
34
|
+
- **Invariant:** One directional light casts the world's shadows, its shadow box covers the play area around the player only, and shadow edges do not shimmer as the player walks.
|
|
35
|
+
- **Technique:** Follow the player with the shadow camera and snap its centre to the shadow map's texel grid. Tune depth bias and normal bias against acne and peter-panning on moving casters. Fade the shadow to nothing over the outer edge of the box rather than cutting it.
|
|
36
|
+
- **Reference configuration:** DK: a 34 m box biased forward of the player, texel-snapped, bias about -0.0003 to -0.00035, normal bias 0.05 to 0.10, the shadow ramped out over the outer 14% of the box, on a 2048 map. SR uses a 120 m box for its island.
|
|
37
|
+
- **Applies when:** Outdoor and large-interior 3D scenes with a sun or moon. A small interior lit only by practicals may use a local shadow instead.
|
|
38
|
+
- **Verify:** Record a slow walk along a wall edge: the shadow's stair-step outline stays still. Shrink the box on purpose and check the edge fades instead of cliff-cutting.
|
|
39
|
+
|
|
40
|
+
### Shadow is darker than light
|
|
41
|
+
- **Invariant:** Shadowed surfaces are clearly darker than lit ones of the same material, and the difference is warm against cool.
|
|
42
|
+
- **Technique:** Lower the fill before raising the key. Measure a lit surface and its shadowed neighbour in a linear capture, not by eye on a bright monitor.
|
|
43
|
+
- **Reference configuration:** Shadowed at 15 to 40% of lit across our games; the ST look pass targets 15 to 20%. MC: sun 3.5 at about 17 degrees elevation, hemisphere 0.18, ambient 0.34, environment 0.30. DK contrasts a cold moon (0xa8c0f0, 2.6) with warm sodium practicals (0xffb765, 5 cd, 22 m, decay 2).
|
|
44
|
+
- **Applies when:** Lit 3D looks. Stylised looks state their band count and ratio in the look bible instead.
|
|
45
|
+
- **Verify:** Sample the luminance of matched lit and shadowed pixels in a capture with the grade off and report the ratio.
|
|
46
|
+
|
|
47
|
+
### A fixed pool of real lights
|
|
48
|
+
- **Invariant:** The number of real point and spot lights never changes during play, so no shader recompiles mid-game, and a lit light never jumps to a new position.
|
|
49
|
+
- **Technique:** Create the pool once and leave it in the scene. Each frame, show the strongest authored sources through it, swap a source in only when it clearly outranks the weakest shown one, and hand a slot over on the frame its intensity is exactly zero. Never toggle `visible` on a light; set intensity to zero. [helpers/light-pool.js](helpers/light-pool.js) does this, and its `selfTest()` plants a shrinking pool, a ranked pool and a pool without fades to prove its checks.
|
|
50
|
+
- **Reference configuration:** DK shows about 68 authored lamps through a small pool: 4, 6 or 8 real lights by quality tier, 1.7 times hysteresis, 0.25 s fades. DK defines a lit-light teleport as a pooled light moving more than 0.25 m in a frame with non-zero intensity, excluding sources that really moved.
|
|
51
|
+
- **Applies when:** More authored lights than the budget allows real ones, which is almost every level with lamps.
|
|
52
|
+
- **Verify:** `renderer.info.programs.length` is unchanged after walking the whole level past every lamp, and the helper's `measurePool` reports zero count changes and zero lit teleports.
|
|
53
|
+
|
|
54
|
+
### Real indirect light
|
|
55
|
+
- **Invariant:** Light bounces: a sunlit floor warms the wall beside it and a dark corridor is darker than an open courtyard, from an actual bounce solution rather than a brighter ambient.
|
|
56
|
+
- **Technique:** Bake it. Per-vertex or lightmapped irradiance for static geometry, plus a grid of spherical-harmonic probes sampled by moving actors. three's `LightProbeGrid` (examples, WebGL only) bakes probe grids on the GPU; lightmaps can be baked offline. Hemisphere fill, environment maps and ambient occlusion are not global illumination, and calling them that is a false claim.
|
|
57
|
+
- **Reference configuration:** SR bakes single-bounce irradiance into a per-vertex atlas for static geometry and nine-coefficient SH probes for actors, validated against a signature of the world so a stale bake refuses to load. It is the only one of our four games with real indirect light, and its scenes hold up for it.
|
|
58
|
+
- **Applies when:** Any game that wants depth from light, most of all interiors and mixed indoor and outdoor spaces. A flat style chosen in the look bible may skip it.
|
|
59
|
+
- **Verify:** Isolate the indirect term in a debug view: it varies across the level and is darker in enclosed spaces. Keep the bake source and confirm the shipped data matches the shipped geometry.
|
|
60
|
+
|
|
61
|
+
### Emissive is not a light
|
|
62
|
+
- **Invariant:** Anything that looks like it lights its surroundings does light them, through a real light in the pool or a baked contribution.
|
|
63
|
+
- **Technique:** Pair each practical (lamp, screen, fire, sign) with a pooled source or a baked contribution. Flicker a practical on three detuned sines and drive its emissive from the same value so the bulb and the light agree.
|
|
64
|
+
- **Reference configuration:** DK's practicals (hanging lamps, wall lamps, fluorescents, emergency domes, fires) are driven per frame with their emissive following the light.
|
|
65
|
+
- **Applies when:** Any scene with visible light sources.
|
|
66
|
+
- **Verify:** Turn a practical's light off in a debug build: the surfaces near it change, not just the bulb.
|
|
67
|
+
|
|
68
|
+
### Nothing on the camera lights the world
|
|
69
|
+
- **Invariant:** No light attached to the camera or the player's view model reaches the world pass.
|
|
70
|
+
- **Technique:** Put view-model lights on the view model's own layer and pass. A camera-parented light moving at player speed defeats shadows, pools and every measurement of the rig.
|
|
71
|
+
- **Reference configuration:** DK's weapon rig carries a fill light parented to the camera on its own layer, a key 1.34 and a cool rim 0.44 for the weapon only; its pool measurements exclude that fill as a source that really moves. OC moved its fill lights near the hands away and lower and halved them, instead of dimming the scene. OC's third-person muzzle light is about 0.12 of the first-person one, 30 cm ahead of the gun.
|
|
72
|
+
- **Applies when:** First-person games and any game with a view model.
|
|
73
|
+
- **Verify:** List lights at runtime with their parent chain and layers; none under the camera is on the world layer.
|
|
74
|
+
|
|
75
|
+
### Environment for reflections
|
|
76
|
+
- **Invariant:** Reflective materials reflect something real: the sky, or a probe of the place.
|
|
77
|
+
- **Technique:** A PMREM of the sky in `scene.environment`, or a captured cube of the level, regenerated after a lost WebGL context. Where areas differ, give each its own environment, and set reflection strength per material class (`envMapIntensity` in three.js).
|
|
78
|
+
- **Reference configuration:** DK bakes its procedural sky into a 256 PMREM; SR captures a 128 cube. OC's titan chain links at metallic 0.7 mirrored the night sky and went black, and iron without a metal flag read as grey cloth.
|
|
79
|
+
- **Applies when:** PBR looks with any metal or gloss.
|
|
80
|
+
- **Verify:** Capture a metal surface while turning: its highlight and reflection move with the view and match the sky.
|
|
81
|
+
|
|
82
|
+
### Effects take the scene's light
|
|
83
|
+
- **Invariant:** Particles, smoke, blood, rain and other effects are lit by the place they are in, unless they emit light themselves.
|
|
84
|
+
- **Technique:** Turn effect lighting on explicitly, since many particle systems ship unlit, or feed the scene's ambient and nearest light colour into the effect shader. In three.js `SpriteMaterial` and `PointsMaterial` ignore lights: draw lit effects as instanced quads with `MeshLambertMaterial` or `MeshStandardMaterial`, or pass a light colour uniform sampled from a `LightProbe` or the light pool.
|
|
85
|
+
- **Reference configuration:** OC's particles were unlit by default, so its blood read "salmon pink" in 3 reports and was never fixed.
|
|
86
|
+
- **Applies when:** Any lit 3D look with particles. Emissive effects (sparks, muzzle flash, magic) stay unlit on purpose.
|
|
87
|
+
- **Verify:** Fire the same effect in a fire-lit spot and in shadow: its brightness and tint follow the location.
|
|
88
|
+
|
|
89
|
+
### One owner for exposure, one rig per screen
|
|
90
|
+
- **Invariant:** One person or agent owns exposure and light intensity, every change is made against the merged build, and each screen (arena, menu, results) has its own rig.
|
|
91
|
+
- **Technique:** Keep light rigs in a table per screen in the look bible. Make brightness changes relative to the current merged values, not on top of another stream's unmerged boost, and attach a capture to each change.
|
|
92
|
+
- **Reference configuration:** OC's arena boosts leaked onto menu figures and gave them a foil look. Two streams' brightening would have stacked to 2.55 times. A 300,000 rifle light caused the defect agents were chasing, and light powers were "a guess". Lightning is clamped and runs at 25% in cinematics.
|
|
93
|
+
- **Applies when:** Any game where several people or agents touch the look.
|
|
94
|
+
- **Verify:** Diff light values between merged main and each pending change; each screen's capture matches its rig table.
|