NeonRunner

Current Work In Progress project... 

NEON RUNNER / Devlog

The Concept & Core Loop

This project is a 2D auto-runner set in a rain-soaked neon megacity, built for the browser with zero external art or audio assets. Every building, sprite, crane, helicopter and sound effect is drawn and synthesized in code. That was an intentional first move. I wanted to evaluate the game as a *game* before any production asset existed. If the loop is not readable and fun when everything is procedural, better art will not fix it. If it works, the look can grow into something without breaking what works.

This game exists as my portfolio piece. It is a proof of concept that I can design an idea and bring it all the way to completion, not a tech demo or a vertical slice. There are finished levels with bosses, endings, audio direction and a real release build behind them.

The target was one complete, stable loop from start to finish:

> boot splash → menu / level select → skippable intro cutscene → the run → boss fight → scripted escape ending.

Two levels ship in this build. DATA HEIST is a building traversal that ends in a helipad helicopter fight and parachute drop, and THE ESCAPE is a car chase through street, tunnel and countryside. A third level, a stealth prequel, exists in prebuild stage. More on it later in this post.

The run itself is deliberately simple to read. You always move right at a pace the game controls, and your agency comes down to four verbs. Jump, slide or dash, hold shield, swing sword. Obstacles are things to hop over, laser walls are things to duck under, drones fly in to be swatted on sight, and enemy bullets can be deflected back into their owners. I wanted a player to understand what they can do within seconds of the first frame. No mode selection, no setup, just one readable lane ahead that asks "jump or not" constantly. The harder verbs layer in only after the basics are felt.

Developer / QA Testing Tools

Because I was both designing and testing this game, I built an internal tuning layer so systems could be verified without luck or grinding. It is a pause menu console exposing hundreds of live dials, covering every parallax layer's visibility, position and speed, per-kind obstacle gates, player and combat floats including hitboxes and fire rates, audio buses, and level-specific sections that only appear while that level is paused. The key design decision was LIVE MODE. Opening the console does not freeze the game, so you can adjust a dial mid-run and watch the effect immediately. That turned out to be how most of the feel work actually happened. Slow motion depth, glass slowdown factors and drone fire windows all got tuned live. Dials persist across sessions with save and reset semantics, so a found look is never lost by accident.

The second tool was a headless test suite. My development environment has no browser at all, so every system also runs under Node through sandboxed probes that cover full app boot flows, music state-machine audits (exactly one track swap at the cutscene handoff, dirge once per game over), level validators that reject unjumpable gaps, and targeted mechanic checks. A hard project rule came out of this. The console must stay clean. A validator warning or a JS error counts as a failed change. Design tools are not separate from design work here. If I cannot reproduce a state directly in the game or in a probe, I cannot tune it honestly.

For the release build those tools are deliberately locked behind shipping flags, so what players get is clean while everything underneath stays intact for future builds.

One honest note on process. Code generation was AI assisted, and that speedup is what made this scope possible while keeping iteration fast. The design itself was mine from start to finish. Every system, mechanic, level decision, art direction call and tuning pass came from human playtesting and judgment. This devlog describes what I designed.

Level Design & Fairness (DATA HEIST)

The level is built from zones. Interior offices, balcony gaps and rooftop sections. Two invariants do most of the fairness work.

- **One running surface.** The floor line is identical in every zone, whether office or rooftop. Vertical reading never changes under you, and the only vertical threat is a gap. Gaps are voids.

- **Gaps sized against reach, not taste.** Every gap width is validated at load against jump reach *at local speed* with a safety margin. The validator warns if any gap could ever be unjumpable. Difficulty comes from spacing and what's next, never from an impossible jump.

Obstacles follow a small grammar. Desks, racks and wall stubs get jumped over, laser walls get slid under. Their order matters too, because the first obstacle in the level is always the self-evident kind (more on that below). Checkpoints enforce a placement rule rather than trusting it. A respawn point must be on solid ground with at least 250px of runway before the next void. You can never reboot into a pit, because "never" is checked and not hoped for.

Escalation is spatial, which means you *see* the level getting meaner as you progress. Drones only animate in once their hover point enters your camera view, and the closest helicopter plane does not even start spawning until you are past half the map. The run ends on an elevated helipad deck where auto-run switches off entirely. The last stretch is a manual walk arena, and it reads clearly as "the pace changed because something important happened."

How The Level Is Built. One World, Not Swapped Scenes

A runner that moves between indoor offices and outdoor balconies or rooftops has a rendering problem. Every time you cross a boundary, what is visible changes from interior walls to sky and city. The obvious solution is to swap scenes or crossfade layers at each boundary, and it shows. You can *feel* the screen changing, and respawning mid-transition can leave half the world in the wrong state.

I did it differently. **The entire level is one continuous world, and every layer of every zone exists on screen at all times.** The office interiors, rooftop parapets, balcony edges, indoor foreground strips and outdoor skyline are all there from start to finish. Nothing gets spawned or destroyed as you run. What changes is only which parts are *masked out*.

Each outdoor area (balcony gap, roof section) defines a spatial culling zone over the screen. Indoor layers render in full but become see-through exactly where those zones sit. That means through an office window you see the actual street outside that specific window's position, and from a rooftop you can look down into the interior behind you. The masks extend slightly past each zone's edges so seams tuck under door slabs instead of showing hairlines of wrong geometry.

That choice buys three things. First, there is no pop-in or scene swap at any boundary, so the building reads as one structure you are moving through rather than a series of rooms. Second, visibility is a pure function of where the camera is, which makes it deterministic and respawn safe, so dying mid-transition can never leave the screen half swapped. Third, everything environmental composes for free, because rain, lightning and helicopters render at real depth behind whatever happens to be visible.

The only hard transition in the game is the **door slab**. It is a thin neon wall anchored to world geometry, with magenta trim on exits and cyan on entries. It sits deliberately faint from about 600px out so you cannot tell exactly where the edge is until it arrives, then becomes opaque as it crosses. Interior/exterior state flips on the exact frame the slab passes your position, and zone audio (rain level, helicopter muffle) eases in about 0.4s behind it, so sound lands with the visual rather than before or after. On the big rooftop doors a concrete wall face sweeps across *in front of* you. You disappear behind it and reappear on the other side, which sells going around a corner better than any fade could.

This is also why balcony glass panes work as physical objects. They sit on exactly these office/gap boundaries, right at the seams the masks are built around.

Mechanics & Progression

**The four verbs.** Jump is hold-to-rise and needs no explanation. Slide/dash is a short timed burst with extra speed. In the air it becomes a forward lunge that rams enemies, so the same button is both evasion up close and an attack on the move. The shield is a directional energy bubble. It drains for about two seconds and takes three to recharge, re-arming at a visible 50% line, and it faces where you are going (forward by default, left if you hold back, up while rising fast). It is a resource you spend to protect momentum and block bullets, not a free wall. The sword kills drones on contact and **deflects enemy bolts back into their owners**. Deflected shots kill enemies too, which is the whole combat fantasy of the game. Read the pattern, time one swing, let the bullet do your aiming.

**Tiered punishment.** Hitting an obstacle costs 1 HP plus a red flash, a small hop and about a second at half speed. Walls are there to teach you, not to kill you. Bullets and falling into voids are instant deaths. Three lives per level, three HP each. Respawns come with brief invulnerability at the last checkpoint. The gradient is deliberate. Minor mistakes cost momentum, real mistakes cost a life, and the game tells you which kind of mistake you just made by how hard it hurts.

**Balcony glass panes.** Every office-to-gap edge carries its own one-shot pane. Crossing in the air shatters it, unless you are shielding. Then the bubble eats the impact and you keep full speed. Dashing through only costs a 25% slow instead of the wall-like ~45% momentum loss a plain jump takes. The shards fly outward over the void and drop into the hole on exit faces, or land on the floor inside on entry faces. Every crossing visibly *happens to the building*. The point of this system is that gap traversal becomes a decision rather than a reflex. Spend shield energy now, or eat a slowdown that makes the next obstacle harder. Each pane breaks once, so the level physically changes as you run it.

**Bullet-time teaching moments.** This was the feature I cared most about this cycle, and it came from a simple observation. Jump is self-explanatory. A person hits a wall, gets hurt, and reasons they should jump. But sliding under a laser, holding shield through glass or deflecting a bullet are not intuitive at all. So instead of tutorial text, the game teaches by changing time itself. Once per run, at the moment you first genuinely need one of these moves, the following happens:

- The world slows to ~10% speed for about two real seconds (a classic slowdown whoosh plays).

- The screen dims and a single visual prompt holds center screen. On keyboard it shows keycaps with gesture chevrons. Touch players get hand graphics, like a swiping hand or a tapping finger, once touch input has been detected. No walls of text. The player's own device decides which language to speak.

- **The whole soundscape obeys the slow motion.** Music drags in tempo and muffles, rain and helicopter rotors drop in pitch, lightning waits its turn. Time slows everywhere, not just on the sprites.

Placement mattered as much as the effect itself. The dash help must not start while you are still running up to the first jump-over obstacle, so it fires a quarter second after clearing it and within two player lengths of the laser. The deflect help waits until a bolt is genuinely close, three body lengths out. And the shield help had to land earlier, in front of the first balcony jump rather than after the shatter. Each lesson also consumes itself. Once taught, it never returns in that run. Teaching should be an event, not a nag.

**Drone pacing.** Drones are parked off-screen until their hover point reaches your camera view, then fly in from the top-right and open fire 0.2 to 0.6 seconds after arrival. There is no settle grace period, because a drone that hovers silently for a second reads as decoration rather than threat. A proximity-scaled rotor buzz means you hear them before they are visually obvious, which does half of the warning work.

The Helipad Boss & Parachute Ending

The run ends where it has always been pointing, at an elevated helipad deck on the far edge of the building. Stepping on it triggers a helicopter boss. Auto-run locks off so you walk back and forth manually, an invisible wall keeps you from walking back into the corridor, and the fight is built entirely out of verbs the player already owns. Jump slash hits the rear rotor when it swings by, and deflecting the gunner's bullets back into the pilot drops him (the game calls this "PILOT DOWN"), which arms the rotor's final point. The crash itself is a scripted cutscene with invulnerability held through it. You cannot die mid-cutscene, because dying during your own victory lap would be tone deaf. Then comes the parachute escape off the building. The default finale is a ballistic leap into freefall, while an alternate framing where the whole world scrolls up instead of you falling sits behind a dev dial. Whether to ship both or just one is still open.

Level 2. The Escape (Car Chase)

The second level reuses the same verbs in a new body. You start with a parachute drop onto a street, run behind a trailing cop cruiser past smashable road-closure barriers, into a mountainside tunnel that alternates closed stretches with see-through window bands, and out into open countryside where pursuit bikes rubber-band around you. The finale is a VTOL intercept. Its figure 8 flight path is hard capped to the upper side of the screen so it can never dip low enough to be cheated by staying on the ground.

The design lever I am most proud of here is **staged car damage**. Hits accumulate in visible tiers. Dented hood first, then smoke, a small fire, dents plus full fire and wobble, and finally severe state. Every speed and response penalty is hard floored so damage can never make the car more than 1.5x worse to drive. Damage escalates *tension* without creating a punishment spiral where one bad hit makes the rest of the level unwinnable. The game gets meaner in a way that still feels like the same game, just deeper, and that is exactly how I want difficulty to work everywhere in this project. Deaths get a longer, grandiose beat (a full car-destruction blast) because dying in a chase should cost you something cinematic, not just a checkpoint rewind.

Playtesting & Versioning

I did not want to balance this purely by gut feeling, so five outside players tested repeated builds while mechanics were added and difficulty adjusted. Their job was specifically hardness versus easiness, covering where people died, which obstacles felt unfair rather than hard, when the teaching moments landed early or late, and whether the boss fight read as fair on a first attempt. After each major tuning pass they retested the new build, and I kept **roughly sixty versioned builds** from the first playable to this final release. That means every balance change could be compared against the last one instead of relying on memory of how the game used to feel.

The clearest example of that loop is the teaching system itself. It went through several placement passes with real feedback. The dash help first fired while players were still running up to the very first obstacle, which was wrong because that moment belongs to jumping. It moved later, then got a fixed delay and a hard distance cap until it landed exactly two player lengths before the laser. The shield help went the other direction. It was firing after the glass had already shattered, so it moved earlier to sit in front of the jump. And the deflect help waited too long at range. Now it triggers only when a bolt is genuinely close enough to matter. None of that would have converged without people actually playing and saying "that felt early" or "that felt late."

Presentation & Feel

The procedural look is not a placeholder budget decision. It is the identity of the game, and I am happy with exactly where it landed. Every visual was built in code and edited under direct direction until it read the way I wanted. Readability was the art direction.

- The parallax city has **headroom**. Every building layer extends above its old top edge, so camera lifts on jumps never reveal sky over a ceiling or cut anything off.

- **Cranes snap to rooftops.** An early version spawned cranes at fixed heights, and whenever a crane's base hovered over a gap it read as broken rather than atmospheric. Now each background crane is seeded into its own skyline area and re-snaps every frame to the closest rooftop below (with a ~0.1s glide so seed changes do not pop). Nothing in this city floats that should not.

- **Rain knows where you are.** The rain loop eases between full outdoor volume and a 20% indoor floor as you cross door slabs. Indoors it becomes a muffled rumble through walls, outdoors a full downpour. Thunder is scheduled *after* its flash with a random half-to-one-second lag, because thunder that arrives together with the lightning is not weather. It is a sound effect.

- A **seeded city**. One dial rolls a fresh skyline and crane layout every start (or locks to a seed for reproducible runs), so no two playthroughs share exactly the same street.

Cinematic Layer

These systems exist to make the game feel like a product rather than a test scene. There is a boot splash with the studio logo video over a procedural 8-bit sting, a ~12 second DATA HEIST intro cutscene (terminal, door burst, two security guards sprinting in and firing choreographed misses while the hero sprints out) that any tap skips instantly, letterbox bars sliding out as control hands off to the run, the boss crash sequence, and the parachute escape framing. All of them are fail safe. A skipped intro still swaps music exactly once, and a failed clip moves forward instead of hanging on black.

Audio & Production Stability

Audio is fully procedural WebAudio on four loudness buses (SFX / music / ambience / helicopter rotor). Two parts of it are the most deliberate.

- **Music flow is a state machine, not a pile of call sites.** The menu plays a chill 96bpm loop. Exactly one swap to the 140bpm run track happens at cutscene handoff, and an automated harness verifies there is exactly one intense start with no variant flips. A slower boss tension track takes over on arena entry, and a slow A minor dirge plays when lives run out. Unmuting mid-game re-derives the correct variant from current state, so sound can never be left permanently silent by an edge case.

- **The soundscape obeys time scale.** During bullet-time lessons everything slows with the world. Music tempo drags, muffle deepens, rotor pitch drops, thunder waits its turn, and a whoosh marks both the plunge into slow motion and the swell back out.

On the stability side, deterministic art is pre-baked to offscreen sprites at init (exit tower, lamp cones, searchlight cone), rain draws as about three batched strokes per frame, and every live dial resolves through an O(1) lookup because it gets consulted dozens of times a frame. A runner that stutters reads as broken even when the logic underneath is fine. Performance work was therefore treated as feel work rather than optimization trivia.

Failures & Honest Weak Points

- **The UI layer is functional, not polished.** It was built for exact control and live tuning, which helped iteration enormously, but it also became the largest area of technical debt. The busiest screens still need cleanup before this feels release quality rather than a well made prototype.

- **My test environment has no browser.** The headless probes catch logic errors and state-machine bugs, but an entire class of problems (audio timing on first keypress in fresh sessions, input edge cases) only surfaces in real playtesting. That gap is why every change ships with written human test steps. The probe suite narrows down where a human has to look, but it does not replace looking.

- **Level 2 was built last**, so its balance is the freshest. It got the most tuning passes late in development, and as the newest level it is also the one I would re-check first before building any future content on top of it.

On The Back Burner

- **Level 0 "INFILTRATION"** is a stealth prequel with patrol guards that have a "huh?" grace window, closets to hide in, and an elevator shaft set piece. It is built and passes its automated smoke test, but it sits in prebuild stage. Completion is queued until I finish other projects.

- **Ceiling turrets** remain disabled by default. The data stays in the level file and can be re-enabled live. They would be the first static pressure system to turn back on if a future build wants more indoor combat variety.

- **The escape framing choice.** Legacy leap versus the world scrolls up mode is still open, though both exist and work.

What This Build Proved

This build succeeded at what it was trying to do. It proves that an idea can be taken from first sketch to a finished, shippable game without over-engineering the structure first. The core systems interlock well enough that the whole thing feels like an actual little product rather than disconnected test pieces. Pause freezes the run exactly where it is while menus animate over it. Win and lose states settle cleanly on top of the frozen game. The boss, crash cutscene and escape chain together without a single jarring handoff. Teaching works with zero tutorial text because time itself does the explaining. And a fully procedural city reads as *inhabited*, with rain muffled through office walls, cranes grounded on rooftops, and helicopters that only get bolder past halfway. Getting this loop stable first made everything else easier to evaluate. Every balance decision since has been answerable inside the game rather than argued about in the abstract.

Future Goals

1. **Store & monetization layer.** Drafted for later, not built yet. The intent is that it supports the gameplay by reducing friction or helping recover from a bad position, and never gates fun behind payment pressure.

2. **Procedural level generation.** The background and city systems are already procedural. The next step is generating *the levels themselves*. Obstacle placement and building/city layouts for new levels, plus sunsets, different city styles and more enemy types, so no two runs share a street.

3. **New gameplay directions.** Concepts already in the pipeline include top-down missions, stealth segments that build on Level 0's guard AI, and sniping missions. Same verbs-and-readability philosophy, new bodies for them.

4. **Score & best times.** The stats plumbing already exists, and a light meta-progression layer comes next after content.

5. **Finish what is queued.** Level 0 completion and the escape framing decision happen when my other projects clear.

Final Takeaway

This project was built around one question. Can I design an idea and bring it all the way to completion? The honest answer is yes. There are two finished levels, a boss, scripted endings, a full audio direction and sixty builds of iteration behind this build. The biggest design lesson from making it is that in a runner, **readability of the next three seconds is everything**. If the player can see what to do before they need to do it, they will trust the pace. And when they do not know how something works yet, the game slows down, dims and shows them exactly once. Teaching by design beat tutorial text. Environment as feedback made a city drawn entirely in code feel lived-in rather than generated. The foundation is solid, the direction for what grows on top of it is clear, and the loop holds together under all of it.