Godot 4 game jam

# AGENTS.md: Godot 4 game jam

This is a Godot 4 project made for a game jam. Finishing beats polish. Polish beats features.

## Jam rules (follow these over any instinct to add things)
1. **Core loop first.** Until the game can be started, played, won or lost, and restarted, only work on that.
2. **Keep a cut list.** When the human asks for something big, offer the smallest version that sells the idea,
   and add the rest to `CUTLIST.md` instead of building it.
3. **Feature freeze** when the human says so (default: 75% of the way through the jam). After that: bugs,
   juice (screen shake, sound, particles), menus, and the build. Nothing new.
4. **Ship a build early.** Get a web export on itch.io (draft page) on day one so the final upload is boring.
5. Never refactor working code in the last few hours unless it fixes a crash.

## Project layout
```
scenes/       one folder per thing: player/, enemies/, ui/, levels/ (each .tscn next to its .gd)
autoload/     global singletons (GameState, Audio) — keep these few and small
assets/       art/, audio/, fonts/ — imported files, never edited by code
```
- Commit `.tscn`, `.tres`, `.gd`, `project.godot`, `export_presets.cfg` and the `*.uid` / `*.import` files.
  Ignore `.godot/` and build output.

## GDScript conventions (Godot 4)
- Static typing everywhere: `var speed: float = 200.0`, `func take_damage(amount: int) -> void:`.
  Use `:=` when the type is obvious.
- `snake_case` for files, functions and variables; `PascalCase` for `class_name` and nodes; `UPPER_SNAKE` for constants.
- Use `@export` for tunable values so the human can tweak them in the inspector instead of asking you.
- Use `@onready var sprite: Sprite2D = $Sprite2D` for child references. No `get_node()` with long paths across the tree.
- Signals for "something happened" (`signal died`, `health_changed.emit(hp)`), direct calls for "do this".
  Children signal up; parents call down.
- Connect signals in code with callables: `button.pressed.connect(_on_start_pressed)`.
- Physics and movement in `_physics_process(delta)`; visuals and input polling in `_process(delta)` or `_unhandled_input`.
- Use groups (`add_to_group("enemies")`) instead of searching the tree.
- Use `await get_tree().create_timer(0.5).timeout` for simple delays; `Tween` (`create_tween()`) for movement and juice.
- Godot 3 syntax is wrong here: no `onready`, `export`, `yield`, `KinematicBody2D`, or `connect("signal", self, "method")`.

## Editing scenes
- Prefer creating nodes in the editor (tell the human what to add) or in code. If you must edit a `.tscn` by hand,
  keep `ext_resource` ids consistent and do not reorder sections.
- Input actions belong in Project Settings → Input Map (`project.godot`), never hard-coded key codes.

## Before you say "done"
- Run the project headless to catch script errors: `godot --headless --quit` (or ask the human to press F5).
- Say what the human should test by hand, in one or two lines.

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `godot-jam-ship`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Godot 4 game jam" v1.0.0 — https://loadout.jnw-it.com/loadouts/godot-4-game-jam/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `godot-jam-ship`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Godot 4 game jam" v1.0.0 — https://loadout.jnw-it.com/loadouts/godot-4-game-jam/ -->

---
description: Godot 4 GDScript style and API rules
globs: "**/*.gd"
alwaysApply: false
---

- Godot 4 syntax only: `@export`, `@onready`, `await`, `signal.emit()`, `signal.connect(callable)`, `CharacterBody2D`/`3D`.
- Type every variable, parameter and return value. `-> void` on functions that return nothing.
- `CharacterBody2D`: set `velocity`, then call `move_and_slide()` with no arguments.
- Use `Input.get_vector("move_left", "move_right", "move_up", "move_down")` for movement; action names come from the Input Map.
- Expose tuning values with `@export` (and `@export_range` where sensible) instead of magic numbers.
- Prefer signals and groups to absolute node paths. Avoid `get_parent().get_parent()`.
- Free nodes with `queue_free()`, never `free()`, during gameplay.
- Keep scripts under ~200 lines; split behaviour into child nodes/components when they grow.

---
name: godot-jam-ship
description: Export a Godot 4 project to the web and publish it to itch.io. Use when the user wants to build, export, upload, publish or submit their game jam entry.
---

# Ship a Godot 4 jam build to itch.io

## 0. Preconditions (check, then tell the human what is missing)
- Godot 4 is on the PATH (`godot --version`) and the **export templates for that exact version** are installed
  (Editor → Manage Export Templates). Headless export fails without them.
- `export_presets.cfg` contains a preset named `Web`. If not, ask the human to add one in Project → Export
  (Add… → Web) and save; do not invent the file from scratch.
- `butler` is installed and logged in (`butler login`, or `BUTLER_API_KEY` set) if publishing.
- The itch.io project page exists (it can be a draft). You need `user/game-slug`.

## 1. Pick threading
- **Thread Support off** (default for Godot 4.3+ Web preset): works anywhere, including itch.io, with no special headers. Use this unless the human needs threads.
- **Thread Support on**: needs cross-origin isolation (SharedArrayBuffer). On itch.io tick
  "SharedArrayBuffer support" in the embed options, or the game shows a blank screen.

## 2. Export
```sh
mkdir -p build/web
godot --headless --export-release "Web" build/web/index.html
```
- The entry file must be `index.html` for itch.io.
- Check `build/web` contains `index.html`, `.js`, `.wasm` and `.pck` files. If the `.pck` is huge, look for
  uncompressed audio or unused assets and mention it.

## 3. Smoke test locally
```sh
npx serve build/web   # or: python3 -m http.server -d build/web 8000
```
Ask the human to open it and play for 30 seconds. Web builds can behave differently from the editor
(audio needs a click to start; mouse capture needs a user gesture).

## 4. Publish
```sh
butler push build/web user/game-slug:html5 --userversion "jam-$(date +%Y%m%d-%H%M)"
butler status user/game-slug:html5
```
- First push only: the human must set "Kind of project" to HTML on the itch page and tick
  "This file will be played in the browser" for the html5 upload, and set the viewport size to the project's window size.

## 5. Optional desktop builds
If presets exist: `godot --headless --export-release "Windows Desktop" build/win/game.exe` then
`butler push build/win user/game-slug:windows`. Same for `Linux` and `macOS` (macOS builds are unsigned — tell the human players will need to right-click → Open).

## 6. Report
Tell the human: the itch.io URL, the channel(s) pushed, the build version string, and anything that still needs a click on the itch dashboard. Do not submit to the jam itself — that is the human's button.