- GDScript 95.8%
- PowerShell 2.8%
- GDShader 1.3%
- Batchfile 0.1%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| resources | ||
| scenes | ||
| scripts | ||
| shaders | ||
| tests | ||
| tools | ||
| .gitignore | ||
| dev.cmd | ||
| dev.ps1 | ||
| general-instructions.md | ||
| icon.svg | ||
| icon.svg.import | ||
| project.godot | ||
| README.md | ||
fps-blaster
Single-player arena FPS prototype in Godot 4.6, built entirely from the command line (no editor needed). Old-school low-poly look in the spirit of the first Quake. Theme is still undecided, so all art and enemies are placeholders.
The two pillars:
- Locational damage, for everyone (player included). Head > torso > limbs.
- Very clear hit feedback. You always know that you hit, where you hit, and where you got hit.
Quick start
./dev.cmd # build + test (same as: ./dev.cmd all)
./dev.cmd run # play
./dev.cmd test -Filter hitbox # run only tests whose name contains "hitbox"
./dev.cmd capture # boot the game, stage combat moments, save screenshots to captures/
dev.cmd wraps dev.ps1 with -ExecutionPolicy Bypass, so it works without
changing your PowerShell policy. Godot is found via $env:GODOT, then
godot4/godot on PATH, then the newest Godot_v4.*_console.exe under
~/Desktop/Game Dev, ~/Desktop, ~/Downloads, %LOCALAPPDATA%/Programs or
C:/Godot. Set $env:GODOT to pin a specific executable.
| Task | What it does |
|---|---|
build |
--import (refreshes the global class cache), then loads every script/scene/resource/shader and fails on any compile or load error. |
test |
build, then the headless test suite. Exit code 1 on any failure. |
run |
Imports, then launches the game window. |
capture |
Imports, then runs tools/capture.tscn in a window and saves PNGs (arena, body hit, headshot, headshot kill, gibs, scattergun, player headshot, pause menu, settings). Handy for checking visuals without the editor. |
Controls
| Input | Action |
|---|---|
| WASD / arrows | Move (Quake-style: friction, air strafing, hold Space to auto-hop) |
| Mouse | Look |
| Left mouse | Fire (hold for auto) |
| 1 / 2, mouse wheel | Blaster / Scattergun |
| Esc | Pause menu (Esc again resumes, or backs out of Settings; R restart, Q quit) |
| R / click | Restart after death |
| F2 | Toggle the retro posterize filter |
Bindings are registered in code: scripts/core/input_setup.gd.
Pause menu and settings
Esc (or losing window focus) pauses the game and opens the pause menu: Resume, Settings, Restart, Quit. Clicks land on the menu, not the game, so clicking outside a button no longer resumes.
Settings → Audio has volume sliders for Master, SFX and Music
(0-100 %, 0 mutes the bus). Changes apply immediately and are saved to
user://settings.cfg (on Windows: %APPDATA%/Godot/app_userdata/FPS Blaster/),
then reloaded at startup.
The Master, SFX and Music audio buses are created in code by
scripts/core/audio_settings.gd; there is no
bus layout file. Every Sfx sound plays on SFX. Nothing plays on Music
yet: future music players should set bus = AudioSettings.MUSIC.
Gameplay
- Endless waves in a walled arena. Wave n has
2 + ngrunts andfloor(n / 3)brutes. - Grunt: 100 hp, fires an orange projectile after a short telegraph (arm raise + rising whine).
- Brute: 320 hp, 1.35x size, slower, bigger blue projectile, helmeted (head multiplier 1.75 instead of 2.5), and mostly ignores body-shot stagger.
- Blaster: precise hitscan, infinite ammo, 25 dmg. Two headshots kill a grunt; body shots need four.
- Scattergun: 10 pellets x 9 dmg, 5.5 degrees of spread, uses shells. Each pellet resolves its own body part.
- Pickups: health (+25, refused at full health) and shells (+10), respawning after 15 s.
- Score: archetype points, x1.5 for a headshot kill.
- Waist-high crates hide legs, which rewards aiming high.
Locational damage
Every character carries a HumanoidRig: six box parts (head, torso, 2 arms,
2 legs), each with a Hitbox (Area3D) sized exactly to its mesh. The player
wears the same rig with the meshes hidden, so enemy shots use the same zones.
A ray or projectile hits a Hitbox → Hitbox.receive_hit() creates a
HitInfo with the body part → the character's Health multiplies the base
damage by its DamageProfile for that part → signals drive all feedback.
| Profile (resources/profiles/) | Head | Torso | Arm | Leg |
|---|---|---|---|---|
| Player | 2.0 | 1.0 | 0.5 | 0.6 |
| Grunt | 2.5 | 1.0 | 0.5 | 0.6 |
| Brute | 1.75 | 1.0 | 0.4 | 0.5 |
Body parts also change reactions:
- Enemies stagger by zone (head 0.55 s, torso 0.22 s, leg 0.18 s, arm 0.12 s),
scaled by
stagger_resist. A stagger of 0.2 s or longer cancels an attack that is winding up, so headshots interrupt. - Getting hit punches and shakes your view by zone. Head hits hit hardest.
Movement capsules and hitboxes are on separate physics layers (scripts/combat/layers.gd): shots ignore capsules and resolve straight to a body part. A shot through the gap between the legs is a miss.
Hit feedback
When you hit something
- Hitmarker X by zone: limb = small grey-blue, torso = white, head = large gold with sparks and a pop, kill = red and spreading outward.
- Callouts under the crosshair:
HEADSHOT,KILL,HEADSHOT KILL. - Floating damage numbers at the hit point, coloured and sized by zone (headshots get a "!"). Killing blows get a red outline. Shotgun pellets are summed per target and part, so a blast reads as a few clear numbers.
- The struck body part flashes white (the rest of the body pulses) and flinches away from the shot. Head snaps back, limbs swing.
- Chunky square blood particles (twice as many on headshots) and a knockback nudge.
- Distinct synthesized sounds: dull thud (limb), thwack (torso), metallic "ding" (head), plus a two-tone kill confirm.
- Kills burst the body into physics gibs, one per part. The struck part is thrown hardest, and a headshot kill pops the head up and away.
- Misses: dust and sparks, a scorch mark and a tracer, so hits and misses never look alike.
When you get hit
- Paper doll next to your health: the zone that was hit flashes, and the colour tracks overall health. Head hits rattle the doll.
- Hit-location text (
HEAD -20). - Red screen-edge flash scaled by damage, plus a white flash on headshots.
- Red wedges around the crosshair pointing toward the shooter.
- View punch and shake by zone. Head hits add a ringing "tinnitus" sound.
Retro look
- Renders at 640x360 and upscales by whole-number steps (
stretch/mode=viewport,scale_mode=integer), using the Compatibility renderer. - Procedurally painted 16-64 px textures with quantized colours (scripts/fx/retro_textures.gd), nearest filtering, world-space triplanar mapping on level geometry.
- Low-poly box characters with glowing eyes and arm cannons. Hex-barrelled viewmodels.
- Square particles, flickering torch lights, a banded pixel sky (shaders/retro_sky.gdshader), and an optional posterize + ordered-dither post filter (shaders/retro_post.gdshader, F2).
- 8-bit, 11 kHz synthesized sound effects, generated at startup (scripts/fx/sfx.gd). No audio files.
Project layout
project.godot engine config (hand-maintained)
dev.ps1 / dev.cmd build / test / run / capture
scenes/main.tscn entry scene → scripts/game.gd
scripts/
game.gd builds world, HUD, spawner; pause/restart/score
core/input_setup.gd input actions in code
core/audio_settings.gd audio buses, volumes, settings file
combat/ BodyPart, DamageProfile, Health, Hitbox, HitInfo,
Combat (ray tracing + hitscan), ShotResult, Layers
characters/humanoid_rig.gd box body + hitboxes + flash/flinch + gibs
enemies/ Enemy (AI state machine), EnemyArchetype, Projectile
player/player.gd movement, view punch, pickups
weapons/ WeaponData, WeaponController (firing + viewmodel)
fx/ Sfx (autoload synth), RetroTextures, HitFx, Gib
ui/ Hud, HitMarker, DamageOverlay, PaperDoll, PauseMenu
world/ Arena (geometry, lights, navmesh), Pickup, WaveSpawner
resources/ .tres data: weapons, enemy archetypes, damage profiles
shaders/ post filter, sky
tests/ headless test framework + suites
tools/ build check, capture tool
Gameplay nodes are built in code rather than in .tscn files, so nothing
depends on the editor. Tunable data lives in .tres text files.
Adding content
- New enemy type: copy resources/enemies/grunt.tres,
point it at a damage profile, and add it to
WaveSpawner.composition(). - New weapon: copy resources/weapons/blaster.tres
and add it to
WeaponController.LOADOUT. - Real art later: swap
HumanoidRigmeshes for an imported model and keep theHitboxnodes (e.g. onBoneAttachment3Ds). The damage and feedback code only cares aboutHitbox.part.
Tests
tests/test_runner.tscn discovers tests/test_*.gd. Each test_* method runs
on a fresh TestCase node and may await physics frames. Engine and script
errors raised during a test count as failures (captured via a Logger), and
the runner has a watchdog, so a broken test can't hang the run. Coverage
includes:
- damage maths and profile ordering
- rays resolving to the right zone (including gaps and scaled rigs)
- hitscan damage by zone
- scattergun pellet grouping
- enemy stagger and interrupts
- a full AI spot → telegraph → shoot loop
- gibbing
- player projectile damage by zone
- Quake movement (speed cap, strafe-jump gain)
- HUD feedback wiring
- audio buses, volume persistence and the pause/settings menu
- generated sounds and textures
- the arena navmesh bake