# Repository Guidelines

## Project Structure & Module Organization

This is a Godot 4.6 project. The entry scene is `res://elements/game/game.tscn`, configured in `project.godot`. Gameplay and reusable scene content live under `elements/`, with entity scenes grouped by type, for example `elements/entities/door/door.tscn` and `door.gd`. Data resources are in `data/`, including FuncGodot entity definitions, FGD resources, and map settings. Root scripts such as `character_body_3d.gd`, `grid.gd`, and `runtime_world_environment.gd` support core world behavior. Art and level-authoring assets are split across `assets/`, `textures/`, `shaders/`, and root `.map` files. `addons/func_godot/` is vendored plugin code; avoid unrelated edits there.

## Build, Test, and Development Commands

- `godot --editor project.godot`: open the project in the Godot editor.
- `godot --path .`: run the configured main scene.
- `godot --headless --path . --quit`: load the project headlessly to catch import or script parse errors.
- `python3 tools/lowercase_textures.py`: normalize texture filenames when adding TrenchBroom textures.
- `python3 tools/fix_stale_tres_paths.py`: repair stale `.tres` paths after resource moves.

Run commands from the repository root.

## Coding Style & Naming Conventions

Use UTF-8 text files, matching `.editorconfig`. Follow Godot GDScript conventions: tabs in `.gd` files, `snake_case` for variables, functions, signals, input actions, and resource filenames, and `PascalCase` for `class_name` classes. Keep scene/resource paths lowercase and descriptive, especially under `elements/entities/` and `data/entities/`. Prefer editor-managed changes for `.tscn`, `.tres`, `.import`, and `project.godot`.

## Testing Guidelines

No automated test framework is currently present. Validate changes by loading the project headlessly and running the main scene. For entity or map changes, open relevant `.map` files in TrenchBroom/Godot, rebuild through FuncGodot as needed, and smoke-test collision, triggers, lighting, and shader behavior. Name any future tests after the system under test, for example `test_door_interaction.gd`, and keep them near a dedicated test directory if one is introduced.

## Commit & Pull Request Guidelines

This checkout has no Git history available, so use concise imperative commits such as `Add torch entity shader` or `Fix door trigger resource path`. Pull requests should include a behavior summary, changed scenes/resources, validation steps, and screenshots or clips for visual, lighting, map, or shader changes. Link related issues and call out any required Godot import or TrenchBroom rebuild steps.

## Agent-Specific Instructions

Do not delete `.uid`, `.import`, autosave, or generated resource files unless the task explicitly requires cleanup. Keep generated maps, textures, and FuncGodot configuration paths stable, because resource references are path-sensitive.
