# AGENTS.md — fvtt-hamalron

Foundry VTT **game system** (not a module) for Hamalron JDR, a French-language TTRPG.

System ID: `fvtt-hamalron` · Compatible FVTT v13–v14 · Language: French only (`lang/fr.json`)

## Architecture

| Layer | Location | Notes |
|-------|----------|-------|
| Entrypoint | `fvtt-hamalron.mjs` | ES module, loaded via `system.json` → `esmodules` |
| Models | `module/models/*.mjs` | 12 data models (personnage, pnj, arme, armure, competence, equipement, faction, langue, peuple, region, sortilege, tarot) |
| Documents | `module/documents/*.mjs` | Actor, Item, ChatMessage, Roll (tirage-tarot) |
| Sheets | `module/applications/sheets/*.mjs` | App V2 sheets, one per item/actor type + base classes |
| Config | `module/config/system.mjs` | Exposes `globalThis.SYSTEM` with all game constants |
| Styles | `styles/*.less` → compiled to `css/fvtt-hamalron.css` |
| Templates | `templates/*.hbs` | Handlebars partials |
| Tarot deck | `module/applications/tarot-deck-manager.mjs` | Singleton manager, Fisher-Yates shuffle, GM-only |

## Commands

```sh
# Build CSS (LESS → CSS)
npx gulp css                # one-shot compile
npx gulp                    # default: compile + watch
```

## Linting

```sh
npx eslint .
```

Uses ESLint 9 flat config (`eslint.config.mjs`) with Prettier + JSDoc plugins. Rules: `semi: never`, `quotes: double`, `indent: 2`.

## Compendium pack management

Pack data lives in `packs-system/hamalron-items/` (LevelDB format, used by Foundry at runtime).

The repo has `@foundryvtt/foundryvtt-cli` and tools for YAML ↔ LevelDB conversion:
- `tools/packCompendiumsToDist.mjs` — compiles from `packs_src/` (YAML) to `packs/` (.db)
- `tools/unpackCompendiumsFromDist.mjs` — extracts from `packs/` (.db) to `packs_src/` (YAML)

**Note:** `package.json` scripts reference `pushLDBtoYML`/`pullYMLtoLDB` — these files don't exist yet. Use the tool files directly: `node tools/packCompendiumsToDist.mjs` / `node tools/unpackCompendiumsFromDist.mjs` after creating the source directories.

## Gotchas

- **No tests** exist anywhere.
- **No CI/CD** (no `.github/` directory).
- **No typechecking** — plain JS with JSDoc comments.
- The `system.json` `hotReload` config references `lang/en.json` and `acks.css` — these files do **not** exist. Only `lang/fr.json` is shipped.
- All actor/item sheets are App V2 (unregistered core V1 sheets).
- Tarot deck state is persisted in a world-scope setting `tarotDeckState` (not a `Cards` document).
- Socket event handler is a no-op (`module/socket.mjs`).
- Initiative formula: `1d6` (no decimals).