CubeSiege

# CUBE SIEGE

A neon wave-survival FPS. Cubes rain down on a dusk-lit city block. Kill them for cash, then spend it at the shop (or gamble it at the casino) between waves.

## Play

Double-click **Play.bat**. It installs the one dependency (Ursina) the first time.

Or run it from a terminal: `python main.py` (needs Python 3.10+ and `pip install ursina`).

| Key | Action |

|---|---|

| WASD / Space | move / jump (hold Space = higher, tap = hop, again in mid-air = double jump) |

| C or Ctrl | slide (while running) |

| Shift | dash |

| Right click (hold) | aim down sights |

| V | switch first / third person (see your character) |

| Left click | shoot |

| R | reload |

| M | map (zones, gates, cubes, incoming spawns, chests, wave buttons) |

| TAB | your GEAR (what you wear + your bag) |

| F | your SET POWER (3+ gear pieces of one colour) |

| E | use (wave buttons, shop, hospital, casino games, gates) |

| Esc | pause |

| F11 | fullscreen on / off (also in Settings) |

## Modes

- **PLAY:** the normal wave-survival run.

- **DOOM MODE:** pick a loadout, then build a **kit** on the **DOOM PREP** screen with **Vault money**:

- **UPGRADES:** gunsmith and hospital upgrades for your loadout, overshield and revives.

- **GUNSMITH:** an optic, barrel and magazine.

- **OUTFIT:** gear pieces (8 random offers, REROLL for $100). Common $300, rare $700, epic $1,600, legendary $3,600. 3 of one colour = its set power in the fight.

The kit is **used up when the fight starts**. Win, die or quit, it's gone, and the next attempt needs a new kit. Until you press FIGHT, REFUND KIT gives everything back. TRY AGAIN after a Doom run takes you straight to the prep screen. Doom runs start with $0, because the shops are closed during the fight.

The fight takes place in its own **volcano arena**: a 2x2-zone volcanic biome far from the city, with no other zones around it. It has basalt cliffs, a smoking volcano in the middle that the dragon circles, burning lava pools, basalt columns and obsidian spikes for cover, and a red sky. There's no time limit. It ends when one of you dies. The dragon has 12,000 HP here, so starting gear can beat it. Killing it banks $1,500, and your best time is saved. Doom runs don't go on the wave leaderboard.

- **TUTORIAL:** a guided first run, with one step at a time shown at the bottom of the screen: move, jump, dash, shoot 3 practice cubes, reload, use your SET POWER (you get 3 fire pieces), start and survive a wave, visit the GEAR CAPSULE, the map and your GEAR. You can't die, and tutorial cash isn't banked.

### Movement

You build up speed quickly and slow down smoothly. Walls deflect you along them instead of stopping you, and dash or slide speed carries on for a moment afterwards.

- **Jumping:** hold Space for a full jump, or tap it for a hop. You can still jump a split second after running off a ledge, and pressing jump just before you land counts too.

- **Slide:** while running, press C to drop low and slide fast. Jump out of it to keep the speed.

- **Camera:** it tilts a little when you strafe, dips when you land, and the view widens at high speed. You also hear footsteps and a thud on landing.

### Controller

Xbox, PlayStation (DualShock 4 / DualSense) and most USB gamepads work. You can plug one in at any time.

| Xbox | PlayStation | Action |

|---|---|---|

| Left stick | Left stick | move |

| Right stick | Right stick | look |

| RT / LT | R2 / L2 | shoot / aim |

| A | CROSS | jump (twice = double jump), click in menus |

| B | CIRCLE | use / buy (in menus: back) |

| X | SQUARE | reload |

| Y | TRIANGLE | set power |

| LB | L1 | dash |

| L3 / R3 | L3 / R3 | slide / first or third person |

| START | OPTIONS or PS | pause |

| BACK | CREATE | map |

| D-pad up or RB | TOUCHPAD, D-pad up or R1 | gear (TAB) |

In menus the left stick moves the mouse pointer.

On Windows, PlayStation pads report their sticks and triggers in a different order from Xbox pads. Before this fix that made the camera spin and look up on its own. The game now spots that layout and reads it correctly, and it reads every stick and trigger from its resting position.

### Rebinding (Settings > CONTROLS)

- **KEYBOARD:** click an action, then press the new key. If another action already used that key, the two swap. Mouse buttons, ESC (pause) and F11 (fullscreen) stay fixed.

- **CONTROLLER:**

- **Buttons:** click a row, then press the button.

- **Sticks:** push the stick RIGHT, then UP. The game works out the axis and its direction itself, so even odd controllers can be set up.

- **Triggers:** pull the trigger.

- **Extras:** INVERT LOOK Y, and a live readout of what the sticks are sending, so you can check that nothing drifts.

- **Reset:** RESET TO DEFAULT resets whichever tab you're on.

- **Saving:** bindings are saved in `save.json` (`keys`, plus `pad` per controller name).

### Screens

Fullscreen and windowed both stay on whichever monitor you drag the game to, and the game reopens there next time.

## The city

The city is split into districts on different levels. The layout is the same every run, so you learn it.

- **Central plaza:** the monument and the red NEXT WAVE button.

- **THE PIT** (north-east): a sunken arena 2.4 m deep, with stairs in on two sides, big pillars and low cover. Easy to drop into, harder to get out of.

- **HOSPITAL HILL** (north-west): a raised terrace with the hospital on top, reached by stairs on two sides.

- **SKY DECK** (south-east): a raised deck with the **CASINO** on top.

- **MARKET** (south-west): the **SHOP** and food stalls.

- **Food stalls** (7 around the city, open even during waves): walk up and press E. Neon Soda $10 (+15 HP), Cube Burger $25 (+40 HP), Mega Meal $60 (full heal).

- **NEON STRIP** (east road): the **GUNSMITH**, under a row of neon arches.

Enemies know the floor levels: they take the stairs to reach you on a terrace or down in the pit. If they get too close, double jump out.

## The loop

1. **Break.** The shop, hospital and casino are open. Press E on a red **NEXT WAVE** button when you're ready. There's one in the city and one in every zone you've opened.

2. **Wave.** Survive. Kills pay cash, and fast kill chains (combos) pay more. Every 5th wave brings a boss. **First clear its escort, then the boss arrives.** Boss waves have no swarmer packs. Four bosses take turns:

- **The Monolith** (waves 5, 25, 45...) calls in 3 helpers each time you hurt it past **75%, 50% and 25%** health. It summons nothing in between, so you can clear them and then focus on the boss.

- **The Splitter** (10, 30...) splits into 2 shards when it dies, and each shard splits into 2 chips.

- **The Fortress** (15, 35...) keeps its distance and drops **sentry cubes** that shoot at the same 75 / 50 / 25% health marks. Kill them.

- **The Quake** (20, 40...) leaps up and slams down, sending **shockwave rings** along the ground. **Jump over them.**

3. **Wave cleared.** You get a cash bonus and the next break starts.

- **GEAR CAPSULE** (west of the plaza): a gacha machine. One PULL ($200 + $15 per wave) gives a random gear piece: common 60%, rare 28%, epic 10%, legendary 2%. New pieces go to your bag, and same slot + colour levels up what you have.

- **GEAR SHOP** (the market): 5 gear pieces for cash (common $150, rare $350, epic $800, legendary $1,800), with **new stock every 3 waves**.

- **SELL** tab: every piece you own. Selling pays 40% of its price per level.

- **Gunsmith** (on the Neon Strip), with three tabs:

- **PARTS:** bought once per run, then swapped for free.

- **Optic:** iron sights, red dot, holo sight, or a sniper scope (3.6x zoom, +25% damage while scoped).

- **Barrel:** compensator (half the kick) or long barrel (+15% damage).

- **Magazine:** extended (+40% rounds) or speed mag (35% faster reloads).

- **Grip:** vertical grip (-40% kick, faster aim) or laser sight (tighter hip-fire, with a red beam).

- **Ammo:** hollow point (+20% damage, -15% mag), piercing (shots go through a cube) or shock rounds (hits can zap 2 nearby cubes).

- **UPGRADES:** Hot Rounds (+damage), Big Mags, Fast Hands (reload), plus your weapon's own upgrades.

- **PAINT:** free paint jobs for the body and glow strips, saved between runs.

- **Hospital:** cheap full heal, **Surgery** (+20 max HP, up to 8 levels), **Revive Insurance** (die and wake up in the hospital at half HP), the **Blood Bank** (sell 20 max HP for $200), and the body upgrades: Overshield, Sprint Boots, Blink Core (dash), Field Medic (regen), Iron Skin and Spring Heels (third jump).

- **Casino** (bet any amount, up to all your cash):

- **Slots:** three of a kind pays up to 100x and any pair pays 1.5x. Three skulls curses you: an extra Tank joins the next wave.

- **Roulette:** red/black, odd/even and low/high pay 2x. Green zero pays 36x.

- **Blackjack:** hit, stand or double against the dealer bot. Blackjack pays 3:2.

- **Cube Rocket:** the multiplier climbs until the rocket explodes, so cash out in time. **One launch per break.**

Under the compass, a row of **place icons** shows the shop, hospital, casino, gunsmith, the nearest food stall and (between waves) the NEXT WAVE buttons. If two would overlap, only the closer one shows, and the one you're facing shows its name and distance.

The **backing-up sensor** (bottom of the screen, like a car's parking sensor) lights up yellow, orange then red when a wall is close behind or beside you, and flashes purple with LEDGE when there's a drop behind you (the pit, terrace edges). It beeps faster as you get closer while you walk backwards.

The **compass** at the top has a degree ruler, a heading readout and markers. Enemies show as chevrons underneath (red, gold for elites, white for a bomber with a lit fuse, bigger for big cubes). Chests show as rarity-coloured diamonds above, purple icons show where the next group is about to arrive, and side counters show how many cubes are behind you. Red **arcs** around the crosshair point at whatever hit you, and when only 3 cubes are left, **markers** show them through walls.

Guns have magazines: reload with R, or it happens automatically when the magazine is empty.

## Look and feel

Neon-on-dark: the menus and HUD use Windows' Bahnschrift font, falling back to Ursina's font if it's missing. Buttons are dark glass with a neon strip that lights up on hover, and HUD readouts sit on glass panels. The title screen has a flickering neon logo over the orbiting city, with floating specks. The city sky is tinted to a neon dusk, and glowing dust hangs in the air: one mesh, so it costs almost nothing.

**Cursor:** the game draws its own neon arrow instead of the Windows pointer. It's cyan, and turns pink and grows a little over buttons. Clicks give it a pulse and moving leaves a short light trail. It hides while you play (mouse look).

**HUD:**

- **Wave counter:** a small plate at the top, with the hint or enemy count in a smaller box under it.

- **Set power:** it appears once 3 gear pieces of one colour unlock a power, as a round icon above the ammo panel with its key (F) in the corner.

- While it recharges, a pie wedge in its colour fills clockwise and the seconds left show in the middle.

- **Gear:** 4 little squares above your health show the colour of each piece you wear, next to your best set.

- **XP bar:** a thin bar along the very bottom of the screen, with your level (LV) above it.

- When it's ready the ring lights up with a pop.

- **Ammo panel:** a gun icon in your weapon's colour sits next to the weapon name.

**Shop windows** (gear shop, capsule, gunsmith, hospital, casino, gear, level-up) share one neon frame:

- a dark glass panel with a wash of the shop's colour behind the title

- glowing corner brackets

- a faint light band sweeping down the window

## Loadout and the Vault

There are no classes. After pressing PLAY you see **your character** (holding the chosen gun, with a CUSTOMIZE button under it) and pick a **weapon** and a **trait**. Everyone starts from 100 HP and the same speed, and your trait bends that. Your powers come from the **gear** you find during the run (see GEAR below).

| Weapon | Vault price |

|---|---|

| Blaster: accurate all-rounder | free |

| Storm SMG: full-auto | free |

| Breacher shotgun | free |

| Rocket launcher: rockets recharge, blasts launch you | $1,500 |

| Railgun: pierces whole lines | $2,500 |

| Nail gun: huge magazine | $3,500 |

| Dice cannon: 1-6x damage, crits | $5,000 |

Your weapon adds its own upgrades to the gunsmith (Big Boom for rockets, and so on). Old saves carry over: every class you had unlocked unlocks its weapon.

**Traits** (the third slot) are passives with a trade-off:

| Trait | Vault price | Effect |

|---|---|---|

| Balanced | free | no strengths, no weaknesses |

| Tough | free | +30 max HP, 8% slower, bigger body |

| Swift | free | 12% faster, jumps higher, -20 HP, smaller body |

| Scavenger | $1,200 | +25% cash, food costs half |

| Glass Cannon | $2,500 | +25% damage, -35 max HP |

| Ironclad | $4,000 | take 20% less damage, 10% slower |

**CUSTOMIZE** (main menu, or from the loadout screen) holds free looks that are saved for every run. It has three tabs:

- **CROSSHAIR:** style (cross, dot, circle, chevron, cross + dot, T), size (S / M / L / XL) and colour.

- **CHARACTER:**

- **Body:** body colour, and a pattern (solid, stripes, neon edges, two-tone, belt) in its own colour.

- **Face:** 9 eye styles (including X eyes, hearts and an LED bar) and an eye colour.

- **Gear:** 14 hats (including cowboy, bunny, mohawk and antlers) and 6 accessories.

- **EFFECTS:** dash trail colour (rainbow too) and kill effect.

Every colour row has preset swatches plus a **colour wheel** (the rainbow circle at the end of the row). Drag on the wheel for hue and strength, and on the bar for brightness. The character updates live.

**Click and drag the character** to turn it, on this screen and on the loadout screen. It starts spinning again 2 s after you let go. A **crosshair preview** window under the character shows your crosshair exactly as it will look in game.

**Every run starts with a drop:** you fall out of the sky onto your spawn, seen from behind with a neon streak, and slam down with a shockwave.

You have a body in the game: look down to see it, or press **V** for an over-the-shoulder third-person camera (it slides in close when a wall is behind you, and aiming switches back to first person).

When a run ends (death, quitting or going back to the menu), the cash you're holding is **banked into the Vault**, which is saved forever. Each run still starts with $150.

**Milestones** also pay into the Vault. Clearing wave 10, 25, 50, 75 or 100 shows a gold banner and pays straight into the Vault, so you keep it even if you die a second later: $400, $1,200, $3,500, $6,000 and $10,000. **The first time you ever clear each one pays double.** These don't count in the Tutorial or Doom Mode.

Vault money is spent on:

- **Loadout:** unlock the locked weapons and traits.

- **THE VAULT** (main menu), **POWERS** tab: unlock gear colours. Fire and frost are free; toxic costs $1,500, shock $2,500, void $3,500 and holy $5,000. Old gadget unlocks carried over: Turret → toxic, Missiles → shock, Focus → void, Coin Flip → holy.

- **THE VAULT**, **PERKS** tab: permanent bonuses for every run.

- Seed Money: +$100 starting cash

- Vitality: +10 max HP

- Firepower: +5% damage

- Treasure Hunter: better chests

- Compound Interest: bank +10% more

- Lucky Start: a free starting gear piece

- Second Chance: start with a revive

- Wide Choice: level-ups offer 4 picks instead of 3

## Breakables and loot

Shoot, slam or blow up props to get small pickups. Pickups get pulled toward you when you're close.

| Object | Where | Drops |

|---|---|---|

| Crate | everywhere | $1-10 or +5 HP |

| Supply box (metal, green stripe) | city, Foundry, Ruins | ammo (+30% magazine), $1-10, sometimes +5 shield |

| Crystal | Crystal Field, Ice Yard | **+2 max HP** for the run (sometimes 2 shards) |

| Clay pot | Ruins | $1-10 or +5 HP |

| Glow pod | Toxic Swamp | +5 HP (sometimes 2) |

| Red barrel | city, Foundry, Swamp | explodes (hurts cubes, props and you) |

## GEAR (what you wear in a run)

Gear replaces the old cards and gadgets. These are pieces you **wear** in 4 slots, and they show on your character **over** your free CUSTOMIZE looks. Customize looks have no power; they show again in any empty slot.

| Slot | Gives (common, level 1) | Looks |

|---|---|---|

| HAT | +6% damage | any hat (cowboy, crown, mohawk, antlers...) |

| EYES | +5% fire rate | any eyes (visor, LED, shades...) |

| SUIT | +15 max HP | a body pattern (stripes, neon edges, two-tone, belt) |

| BACK | +3% speed and pickup range | cape, jetpack, scarf... **DRONE PACK / CUBE PET** bring a little helper that shoots for you (no speed) |

- **Rarity** multiplies the stat: rare x1.6, epic x2.4, legendary x3.5.

- **Levels:** the **same slot + same colour** again levels the piece up, +50% per level, up to LV 3.

**The colour is an element.** Wearing several of the same colour builds a set:

| Colour | 2 pieces: your bullets... | 3 pieces: SET POWER on F | Cooldown |

|---|---|---|---|

| FIRE | burn for +25% damage over 2 s | **INFERNO**: a blast of fire around you, and everything hit burns | 14 s |

| FROST | slow cubes by 35% | **FROST NOVA**: freezes every cube near you for 2.5 s (bosses only slow down) | 16 s |

| TOXIC | stack poison (up to 5) | **TOXIC CLOUD**: a poison cloud around you for 6 s | 16 s |

| SHOCK | have a 20% chance to zap 2 nearby cubes | **CHAIN STORM**: lightning jumps through the 8 nearest cubes | 14 s |

| VOID | have a 15% chance to crit for x2.2 | **VOID RIFT**: a black hole where you aim pulls cubes in, then implodes | 18 s |

| HOLY | heal you for 3% of the damage you deal | **HOLY LIGHT**: heal 40%, +50 shield, 2 s invulnerable | 22 s |

With **4 pieces** of one colour, the power gets **+50% power and a 25% shorter cooldown**, and the bullet effect gets stronger.

**Where gear comes from:**

- **XP gems:** every kill drops one (bigger cubes and elites drop more, bosses a lot). Walk near them and they fly to you, and at the end of a wave every gem flies to you. Each **LEVEL UP** pauses the game and offers **3 picks**: new pieces (empty slots and your colours come up more) or a level-up for something you wear. SKIP gives a little cash.

- **Chests:** a piece of the chest's rarity (legendary chests give 2).

- **GEAR SHOP** and **GEAR CAPSULE** (see the city).

**TAB** opens your GEAR screen: what you wear (click to take off), your sets, your level, and your **bag** (click a piece to wear it).

## Treasure chests

After every cleared wave, chests appear in your opened zones. Elites sometimes drop one, and bosses always drop an Epic or Legendary chest. Far zones and heat roll better rarities: **Common, Rare, Epic, Legendary**. Press **E** to open one, even mid-wave. Chests sit on the real floor: in the pit, on terraces and on raised plazas.

## Expanding the map (procedural)

The map is a grid of square zones, and every run starts in the city. During a break, **buy any gate open with cash**: $400 next to the city, $1,600 one ring further out, $3,600 the ring after that. The zone behind it is **generated when it opens**: a random biome (Ice Yard, Foundry, Toxic Swamp, Ruins, Crystal Field), a random layout, one or two enemy types, and its own **NEXT WAVE button**.

A wave started from a zone's button uses that zone's **multiplier**: x2 next to the city, x3 one ring further out, and so on. That means **x2/x3/x4 cash**, and more enemies: **+40% per step** (x2 zone = +40%, x3 = +80%...). The extra enemies make the wave longer, not denser: see Heat for how many are on the field at once.

**Teleports:** each zone has a pink **TO CITY** pad next to its NEXT WAVE button, and the city has a cyan **TELEPORT** pad (south of the plaza, on the compass). That one lists every zone you've unlocked this run, so one click takes you there. Teleports only work between waves. Closed gates show their multiplier, price and a DANGER rating. Enemies arrive around you, usually behind or beside you, 16-38 m away, and path around buildings, doors and gates to reach you. Each group is announced by a warning ring on the ground about a second before it lands:

- **City cubes** fall from the sky onto a red ring with a light beam. Don't stand under them.

- **Frost anomalies** crystallise out of thin air.

- **Swamp monsters** bubble up from a green puddle.

- **Wasps** fly in from the horizon.

If you ever get wedged inside a gate, wall or crate, the game pops you back out onto open ground. Everything resets on a new run.

## Enemies (each area has its own)

A wave uses the monsters of the zone whose **NEXT WAVE** button started it.

| Area | Monsters |

|---|---|

| **City** (cubes only) | Grunt (blue, charges), Runner (orange, fast), Swarmer (tiny, packs of 6), Spitter (green, shoots), Bomber (red, explodes near you or when killed), Tank (purple). Boss every 5th wave: **The Monolith**. |

| **Frost Field** | **Wasp** (flying, circles overhead and swoops down to sting), **Shard** (spinning ice diamond that **blinks** toward you), **Prism** (diamond that fires ice bolts that **slow** you) |

| **Toxic Swamp** | **Slime** (bouncy blob that **splits into 2 slimelets**), **Goo Slime** (spits goo that leaves a **burning puddle**), **Lurker** (swamp thing that **dives underground**, travels to you as a ripple and **bursts out** under you) |

| Foundry | Bombers, Grunts, Tanks |

| Ruins | Grunts, Tanks, Spitters |

| Crystal Field | Runners, Swarmers, Wasps |

Elites (SWIFT / ARMORED / VOLATILE) can appear everywhere from wave 4. Rosters are in `ROSTERS` in `game/config.py`, so new areas such as a volcano or jungle just need a roster and their monsters.

## The Cube Dragon (every 100th wave)

Waves 100, 200, 300... are **survival waves**. A huge dragon made of cubes circles high over **whatever zone you're in**, with no other monsters. It has two attacks:

- **Fireball volleys:** bursts of 3 fireballs that explode where they land. They come faster as it gets hurt.

- **Sky crash:** it climbs out of sight, a **red warning circle** follows you then locks, and it crashes down into it for heavy damage.

You don't have to kill it: **survive the timer** (90 s, +15 s per later dragon) and it flies off and the wave ends with a bonus. Killing it is optional. It has 25,000 HP x its level, any body part can be hit, and it pays a fortune plus **2 Legendary chests**. Tuning is in `DRAGON` in `game/config.py`.

## Leaderboard

Every run that ends in death is recorded in a **local top 10** (name, loadout, score, wave, kills, highest heat, date). Set your name under **Settings**. Each player also gets a stable ID in `save.json`, so the same entries can be uploaded to an online or Steam leaderboard once multiplayer exists.

## Heat

Heat (0–10, the flame in the top-left) is a **live meter**:

- **It rises with every kill.** Elites and splitter pieces give more, a boss gives a lot, and combos add a little. The hotter you already are, the less each kill adds. With no breaks it takes about 3 kills for heat 1, 17 for heat 5 and 44 for heat 10.

- **It drains when you stop killing.** In a wave, after 5 s without a kill it cools about 1 level every 7 s, and the HUD says *"cooling – keep killing!"*. Between waves it waits 12 s, then cools about 1 level every 20 s. Shopping counts as resting. The pause menu doesn't count.

- **The HUD:** the next segment fills up as you kill. The flame flashes gold when you gain a level and blue when you lose one.

What each heat level does:

- **Enemies:** more health and speed, more elites, and **+5% wave size** per level. Wave size is fixed when the wave starts.

- **On the field:** more enemies at once, and more attack turns.

- **Rewards:** **+25% cash and score**.

- **Zones:** new zones are more dangerous.

**How many enemies are on the field at once** depends on heat. The wave's total doesn't change, so a far zone makes a wave longer rather than putting everything on you at once:

| Heat | On the field at once | Cubes attacking you at once | Shooters winding up | Wasps diving |

|---|---|---|---|---|

| 0 | 6 | 2 | 1 | 1 |

| 4 | 13 | 3 | 2 | 2 |

| 7 | 18–19 | 4 | 3 | 2 |

| 10 | 24 (35 is the hard cap) | 5 | 4 | 3 |

**Helldivers-style pressure:**

- **Waiting enemies hold a spot.** Cubes without an attack turn stop chasing and **take up a spot around you, 8–11 m out, on the side they came from**. You end up surrounded, not buried.

- **They follow and swap in.** If you move, the ring moves with you. When an attacker dies, a waiting one steps in.

- **Squads:** a cube with another cube ahead of it (closer to you, in front of it) follows that one, a bit behind and in its own lane (left, middle or right). Enemies arrive in **lines and wedges** that move in sync, and squads hold spots next to each other. A cube breaks formation when it gets its turn to attack.

- **Bosses always attack.**

Explosions (bombers, barrels, rockets) hurt every cube and prop nearby, so you can set up chain reactions. Crates break, and red barrels explode.

From wave 4, any enemy can spawn as a glowing **elite** (SWIFT, ARMORED or VOLATILE) with 2.5x health and a 4x cash reward.

## Graphics

Settings → **GRAPHICS** cycles through four presets. You can also switch each effect separately (the preset then shows CUSTOM):

| Preset | Bloom | Colour grading | Vignette |

|---|---|---|---|

| LOW | off | off | off (plain rendering, fastest) |

| MEDIUM | off | on | on |

| HIGH (default) | on: neon windows, eyes, beams, lamps and the gun glow | on | on |

| ULTRA | MAX: adds a wider halo around bright lights | on | on |

On Medium and above, getting hit splits the colours at the screen edges for a moment, and there's a light film grain.

## Sound and feel

- **Music:** the game composes its own synthwave soundtrack when it starts, with no audio files. There's a calm loop for menus and breaks, a fight loop for waves, and a darker loop for bosses, the dragon and Doom mode. They crossfade on the beat. Music has its own volume slider.

- **Kill streaks:** kills close together call out DOUBLE!, TRIPLE!, QUAD!, RAMPAGE!, MASSACRE! and CUBOCALYPSE!!. Big kills freeze the frame for a split second.

- **HUD icons:** heart, coin, star, flame, bullet and skull icons replace text labels, and the attachments you've equipped show next to your gun.

Your high score and settings (sensitivity, sound, music, FOV, fullscreen, graphics, gun paint) are saved to `save.json`.

## Performance notes

- **Static scenery** is taken out of Ursina's per-frame list (`perf.prune`). **Hidden menu pages and shop windows sleep** until they're shown again.

- **Leak sweeper:** once a second it removes finished timers and animations that Ursina left behind. Before this, they piled up in long fights such as the dragon.

- **Sounds are pre-rendered:** every sound effect is rendered once to a small WAV in `cache/sfx` next to `save.json`. This takes under a second on the first launch only, and 3–4 copies of each sound stay ready in memory. Playing a sound used to cost 11–30 ms each time (the empty-gun click, explosions and gadgets on cooldown all stuttered); now it's about 0 ms. Deleting the `cache` folder is safe: it's rebuilt automatically.

- **Particle pool:** 300 particle cubes are made at load time and reused, and one manager moves them all.

- **Effects budget:**

- At most 300 particles alive and 90 new ones per frame.

- Damage and cash numbers come from a pool of 28 reused texts (max 6 new per frame). The killing blow shows +$ instead of a damage number.

- The same sound plays at most twice per frame, and there's one hit marker per frame.

- **Enemies:**

- Crowd separation uses a once-per-frame snapshot.

- Normal-sized cubes check the nav grid for walls instead of firing a raycast each step.

- The floor check runs every 3rd frame.

## Project layout

```

main.py entry point + game state machine (menu / play / pause / shop / dead)

game/config.py ALL tuning: weapons, enemies, waves, shop prices, slot odds

game/world.py the city map, shop + casino, wave button

game/zones.py the zone grid, gates and the five biome generators

game/teleport.py teleport pads: city -> any unlocked zone, zone -> city

game/nav.py enemy pathfinding (navigation grid + flow field)

game/movement.py momentum, wall sliding, jump physics, slide, camera feel

game/player.py movement, dash, weapons + view-models, upgrades, purchases

game/enemies.py grunt / runner / spitter / tank / boss AI, enemy shots, rockets

game/director.py waves, breaks, rewards, game over

game/gunsmith.py weapon attachments, paint and the gunsmith screen

game/icons.py every icon, drawn in code

game/music.py the generated soundtrack

game/graphics.py post-processing: bloom, colour grading, vignette, presets

game/tutorial.py the guided tutorial steps

game/look.py cosmetics: crosshair, dash trail, kill effects, your character

game/sensor.py the backing-up sensor (walls and ledges behind you)

game/display.py borderless fullscreen / window, multi-monitor aware

game/controller.py gamepad support: per-controller profiles, PlayStation layout, stick/button capture

game/bindings.py keyboard rebinding (on top of Ursina's rebind table)

game/doom_prep.py the Doom Mode kit: bought with Vault money, used up by the fight

game/stores.py the gear shop (rotating stock + sell) and the gear capsule (gacha)

game/volcano.py the Doom Mode volcano arena

game/spawns.py where and how enemies arrive (warning rings, drop/grow/rise/fly-in)

game/ui.py HUD and menus

game/shop_ui.py the shop and slot machine screens

game/casino_ui.py roulette, blackjack and Cube Rocket

game/gear.py gear pieces, colour sets, set powers, XP gems, level-up offers, pets

game/gear_ui.py the TAB gear screen and the LEVEL UP picker

game/chests.py treasure chests: spawning, rarity rolls, opening

game/gadgets.py homing missiles and turrets (kept for later use)

game/dragon.py the Cube Dragon survival boss (every 100th wave)

game/props.py breakables (crates, supply boxes, crystals, pots, pods, barrels), loot pickups, the shared explosion

game/fx.py custom lighting + fog shader, particles, explosions, screen shake

game/sfx.py all sound effects (synthesised at runtime, no audio files)

prototypes/ the earlier 2D and minimal 3D versions

```

To rebalance anything, edit `game/config.py`.