No description
  • GDScript 95.8%
  • PowerShell 2.8%
  • GDShader 1.3%
  • Batchfile 0.1%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-10-31 19:16:17 -04:00
resources first pass for project 2026-10-31 19:16:17 -04:00
scenes first pass for project 2026-10-31 19:16:17 -04:00
scripts first pass for project 2026-10-31 19:16:17 -04:00
shaders first pass for project 2026-10-31 19:16:17 -04:00
tests first pass for project 2026-10-31 19:16:17 -04:00
tools first pass for project 2026-10-31 19:16:17 -04:00
.gitignore first pass for project 2026-10-31 19:16:17 -04:00
dev.cmd first pass for project 2026-10-31 19:16:17 -04:00
dev.ps1 first pass for project 2026-10-31 19:16:17 -04:00
general-instructions.md first pass for project 2026-10-31 19:16:17 -04:00
icon.svg first pass for project 2026-10-31 19:16:17 -04:00
icon.svg.import first pass for project 2026-10-31 19:16:17 -04:00
project.godot first pass for project 2026-10-31 19:16:17 -04:00
README.md first pass for project 2026-10-31 19:16:17 -04:00

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:

  1. Locational damage, for everyone (player included). Head > torso > limbs.
  2. 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 + n grunts and floor(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 HumanoidRig meshes for an imported model and keep the Hitbox nodes (e.g. on BoneAttachment3Ds). The damage and feedback code only cares about Hitbox.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