Colins-Spades/AGENTS.md

AGENTS.md

Guidance for coding agents working in this repository.

Project overview

• Language: Lua (LÖVE game project)
• Entry point: main.lua
• Core code: src/
• Assets: assets/
• Runtime config present: dosbox.conf
• Build system: none (run directly with LÖVE)
• Test framework: none configured in-repo

Repository structure

• main.lua: top-level LÖVE callbacks and state switching
• src/states.lua: game-state registry
• src/gstates/: game states and menu flows
• src/ui/: UI primitives and layout classes
• src/graphics/: sprites/faders/drawable abstractions
• src/sound/: sound managers/effects
• src/utils/: class helper, settings parsing, assets manager, helpers

Build, run, lint, and test commands

This repo does not define a Makefile/npm scripts/CI workflow. Use direct commands.

Run the game

• Run locally with LÖVE:

love .

• Run with debug/skip flags (project-defined args):

love . -- -debug -skip-intro

Build/package

• No packaging script is committed.
• If packaging is needed, use standard LÖVE packaging flow externally.

Lint

• No linter config file is committed (.luacheckrc not found).
• If luacheck is available locally, run:

luacheck main.lua src

Format

• No formatter config file is committed (stylua.toml not found).
• If formatting is needed and stylua exists locally, use:

stylua main.lua src

Tests

• No automated tests are currently committed (no tests/, spec/, or framework config detected).
• There is no native "single test" command in the current repo because no test suite exists yet.

If you add Busted tests, use this convention:

# all tests
busted

# single test file
busted spec/path/to/file_spec.lua

# single test by name filter
busted spec/path/to/file_spec.lua --filter "case name"

Coding conventions

Match existing style before introducing new patterns.

Imports and module layout

• Put imports at the top under a section banner.
• Use local X = require 'path' with single-quoted module paths.
• Keep related imports vertically aligned when practical.
• Return module/class value at file end under -- Module return banner.

Formatting

• Use 4-space indentation (no tabs).
• Keep blank lines between logical sections and method blocks.
• Preserve section banner style used throughout the codebase:
  • ------------------------------------------------------------------------------
  • -- Section Name
• Prefer readable, compact methods; avoid deeply nested branches when simple guard clauses work.

Types and annotations

• Use EmmyLua-style annotations where helpful and already used:
  • ---@class
  • ---@param
  • ---@return
• Keep annotations accurate when signatures change.

Naming conventions

• Files/modules: lowercase with short names (e.g. gstate.lua, sndmngr.lua).
• Class-like tables: PascalCase locals (e.g. GameState, SoundEffect).
• Methods/functions: snake_case (except LÖVE callback names like love.update).
• Fields: snake_case (next_state, current_menu, all_loaded).
• Constants: UPPER_CASE for module constants (SETTINGS_PATH).
• Existing globals in main.lua (Current_state, Fade, etc.) are intentional legacy style; avoid creating new globals unless required.

Object model and inheritance

• Use make_class(...) from src/utils/classes.lua for class-like inheritance.
• Constructors are _init(...) methods.
• Call base constructors explicitly (Base._init(self, ...)) when subclassing.
• Use colon syntax for instance methods (function Class:method(...)).

State-management patterns

• Keep game-flow transitions explicit and deterministic.
• For game states, maintain the established lifecycle shape:
  • _init
  • load
  • update
  • draw
  • unload
  • input handlers as needed
• Return the next state index from update methods where applicable.

Error handling and validation

• Prefer fail-fast error(...) for invariant violations (unknown keys/states, invalid config shape).
• Validate parsed external data before assignment (see src/utils/settings.lua).
• Keep error messages specific and actionable.
• Do not silently swallow invalid state transitions.

Side effects and resources

• Keep resource load/unload explicit for assets, sounds, and UI elements.
• Ensure objects implementing asset-like behavior support load, unload, and is_loaded consistently.
• Be careful with global/shared mutable state (focus handling, active state IDs, fade transitions).

Agent editing rules for this repo

• Prefer minimal, surgical changes that preserve existing architecture.
• Do not introduce new third-party dependencies unless explicitly requested.
• Do not rewrite naming/style globally unless asked.
• When fixing a bug, align with existing state-machine and class patterns.
• Update docs when behavior or developer workflow changes.

Cursor and Copilot rules check

• .cursor/rules/: not present
• .cursorrules: not present
• .github/copilot-instructions.md: not present

If these files are added later, merge their guidance into this document and treat project-specific rules as higher priority.