Added agents instructions

.github/agents/build-fixer.agent.md

@@ -0,0 +1,29 @@
+---
+description: "Use when the CMake configure, build, or v-gears-tests fail. Diagnoses compiler, linker, and dependency errors, then applies minimal style-compliant fixes."
+tools: [read, search, edit, execute]
+argument-hint: "Paste the build error or describe the failure"
+---
+
+You are a specialist at fixing V-Gears build and test failures. Your job is to get the build green with the smallest possible change.
+
+## Constraints
+
+- DO NOT silence errors by disabling warnings, sanitizers, or tests.
+- DO NOT upgrade dependencies, compilers, or the C++ standard — the project is C++14.
+- DO NOT rewrite the CMake `USE_DETERMINISTIC_FALLBACKS` logic; it exists on purpose.
+- DO NOT touch `lib/` (bundled third-party) unless the failure is provably there.
+- Follow `doc/STYLE.md` for any code change; keep diffs minimal and consistent with surrounding code.
+
+## Approach
+
+1. Reproduce: run the failing command yourself (`cmake --build build -j$(nproc)` or `ctest --test-dir build --output-on-failure`) and capture the complete first error — never guess from a summary.
+2. Form one specific hypothesis about the root cause before editing; read the relevant sources/CMake files to confirm it.
+3. Apply the minimal fix and rebuild only the affected target first, then the full build.
+4. If the same error persists after two fix attempts, stop editing and re-read the full compiler output — do not loop.
+5. For sanitizer (`build-asan`) failures, remember the known quirks: luajit must be pre-built uninstrumented, `ASAN_OPTIONS=detect_leaks=0` for builds, and `vptr:*/OgreSingleton.h` is a known UBSAN false positive to suppress, not fix.
+
+## Output Format
+
+- **Root cause** — one paragraph.
+- **Fix** — files changed and why.
+- **Verification** — exact commands run and their results.

.github/agents/ff7-format-researcher.agent.md

@@ -0,0 +1,30 @@
+---
+description: "Use when researching how an FF7 binary file format works, how an existing parser/serializer in src/data implements it, or what the installer decompiler emits. Read-only investigation that returns findings with file references."
+tools: [read, search]
+---
+
+You are a specialist at investigating FF7 binary formats in the V-Gears codebase. Your job is to answer questions about format layouts, existing parsers, and decompiler behavior — nothing else.
+
+## Constraints
+
+- DO NOT edit, create, or delete any file. You are strictly read-only.
+- DO NOT run builds, tests, or any shell commands.
+- DO NOT suggest adding original game data or extracted assets to the repo.
+- ONLY investigate and report.
+
+## Approach
+
+1. Check the format documentation in `doc/code/FFVII/` first.
+2. Find the relevant parser triplet in `src/data/` (`*File`, `*FileSerializer`, `*FileManager`) and read the serializer for the authoritative byte layout.
+3. For installer/decompiler questions, read `src/installer/` and the matching instruction classes under `src/installer/decompiler/`.
+4. Cross-check with the test suite in `test/` — tests often show minimal usage examples.
+5. `_OLD/` contains legacy q-gears code useful as historical reference only; flag it as such if you use it.
+
+## Output Format
+
+Return a concise report with:
+
+- **Answer** — direct answer to the question asked.
+- **Layout/behavior** — field offsets, types, and endianness if relevant, or the call flow for behavior questions.
+- **References** — workspace file paths with line numbers for every claim.
+- **Open questions** — anything not determinable from the code or docs.

.github/copilot-instructions.md

@@ -0,0 +1,57 @@
+# V-Gears Project Guidelines
+
+V-Gears is a free, cross-platform reimplementation of the Final Fantasy VII engine (C++14), continued from the stalled q-gears project. It runs the user's own original game data on modern systems — it is not an emulator and ships no game assets.
+
+## Legal Boundary (never cross)
+
+- NEVER add copyrighted game data to the repo: no ripped textures, models, audio, field scripts, kernel text, or any other extracted asset.
+- Game data is extracted locally by the `v-gears-installer` from the user's own copy of the game, at install time, on the user's machine only.
+- Do not commit screenshots or conversion outputs containing game assets.
+
+## Architecture
+
+- `src/common/` — application base class and file utilities shared by all targets.
+- `src/core/` — engine runtime: audio, console, entities, walkmesh, UI, particles, savemap, `ScriptManager` (Lua bindings via luabind/LuaJIT).
+- `src/data/` — FF7 binary format parsers (LGP, LZS, HRC, TEX, field files, worldmap TXZ...). Most formats follow a triplet: `*File` (data), `*FileSerializer` (read/write), `*FileManager` (Ogre resource loading).
+- `src/installer/` — Qt data installer (`v-gears-installer`); includes the script `decompiler/` that converts field/world scripts into Lua.
+- `src/map/`, `src/modules/`, `src/viewer/` — field map code, game modules (e.g. worldmap), and the model viewer.
+- `lib/` — bundled third-party code (luabind, luajit, sfxdump). Do not restyle, modernize, or refactor these.
+- `test/` — Boost.Test suite mirroring `src/` paths; sources are listed manually in `test/CMakeLists.txt`.
+- `data/` — runtime configuration only (Ogre plugins/resources cfgs). Not game data.
+- `doc/` — all guides; `doc/code/FFVII/` documents the original binary formats.
+- `_OLD/` — legacy q-gears code kept for reference. Do not modify or reuse without asking.
+
+## Build and Test
+
+Dependencies and details: see [doc/BUILD.md](../doc/BUILD.md).
+
+```bash
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug       # configure once
+cmake --build build -j$(nproc)                      # build everything
+cmake --build build --target v-gears-tests -j$(nproc)
+ctest --test-dir build --output-on-failure          # run the test suite
+```
+
+- Always build out-of-source (`build/`, `build-normal/`, `build-asan/`); never in-tree.
+- Main targets: `v-gears` (engine), `v-gears-installer` (data installer), `v-gears-tests`.
+- CMake option `USE_DETERMINISTIC_FALLBACKS` (default `ON`) pragmatically finds libraries; set it `OFF` for clean dependency diagnosis or packaging.
+- Binaries are picky about working directory and cfg files — read [doc/RUN.md](../doc/RUN.md) before launching anything.
+
+## Code Style
+
+Follow [doc/STYLE.md](../doc/STYLE.md) (C++) and [doc/STYLE-LUA.md](../doc/STYLE-LUA.md). Non-negotiable core rules:
+
+- C++14 only. No newer standard features, no GNU/compiler-specific extensions.
+- Files `PascalCase.cpp` / `.h`; types and functions `PascalCase`; variables `snake_case`; class data members `trailing_underscore_`; constants and enumerators `UPPER_SNAKE_CASE`.
+- `#pragma once` include guards; include order: C++ stdlib → C system → other libraries → related header → V-Gears headers.
+- `const` before the type, `nullptr`, prefix `++i`, `explicit` single-argument constructors, `override` on overridden virtuals.
+- Readability over performance; consistency with surrounding code beats personal preference.
+
+## Sanitizer Builds (ASAN/UBSAN)
+
+Verified working recipe — keep these quirks intact:
+
+1. Pre-build luajit without sanitizers (host build tools break under ASAN): `cmake -S . -B build-normal -DCMAKE_BUILD_TYPE=Release && cmake --build build-normal --target liblua -j6`, then copy its generated headers into the ASAN build dir.
+2. Configure `build-asan` with `-DCMAKE_C_FLAGS='-fsanitize=address,undefined -fno-omit-frame-pointer -g'` (same for CXX flags, plus `-DCMAKE_EXE_LINKER_FLAGS='-fsanitize=address,undefined'`).
+3. Build with `ASAN_OPTIONS=detect_leaks=0` (luajit host tools have benign leaks).
+4. Run with a UBSAN suppression for `vptr:*/OgreSingleton.h` — a false positive inherent to OGRE's singleton pattern, not a real bug.

.github/instructions/cpp-style.instructions.md

@@ -0,0 +1,43 @@
+---
+description: "Use when writing or editing C++ code (.cpp/.h files). V-Gears C++14 style rules: naming, includes, const usage, casts, class layout, and documentation."
+applyTo: ["**/*.cpp", "**/*.h"]
+---
+
+# V-Gears C++ Style Essentials
+
+Full guide: [doc/STYLE.md](../../doc/STYLE.md). Key rules enforced on every change:
+
+## Language
+
+- C++14 only — nothing newer, no GNU extensions. Must compile with the project's existing toolchain.
+- Exceptions are allowed; specify `noexcept` when useful and correct.
+- Avoid RTTI (`dynamic_cast`, `typeid`) except in tests. Avoid macros, complicated templates, and forward declarations (acceptable only to break include loops).
+
+## Naming
+
+- Types, functions, methods: `PascalCase` (`MyExcitingClass`, `AddTableEntry()`).
+- Variables and parameters: `snake_case`; private/protected class members get a trailing underscore (`data_member_`).
+- Constants and enumerators: `UPPER_SNAKE_CASE`.
+- Files: `PascalCase.cpp` / `PascalCase.h`; every `.cpp` has a matching `.h` except `main()` files and tests.
+
+## Files and Includes
+
+- `#pragma once` for include guards. Headers must be self-contained.
+- Include order, no blank lines between groups: C++ stdlib → C system → other libraries → related header → other V-Gears headers. No relative paths in includes.
+- Don't inline functions except trivial ones (~10 lines, no loops/switches).
+- Give `.cpp`-only code internal linkage with `static`; never in headers.
+
+## Code Constructs
+
+- `const` before the type: `const int* foo`, not `int const* foo`.
+- `nullptr` for pointers, `'\0'` for chars, `sizeof(varname)` over `sizeof(type)`.
+- C++ casts (`static_cast<>`), never C-style casts except to `void`.
+- Prefix `++i` unless postfix semantics are needed.
+- `explicit` single-argument constructors; `override` (or rarely `final`) on all overridden virtuals.
+- Classes: data members private; section order `public:` → `protected:` → `private:`; structs only for passive data.
+- Prefer return values over output parameters; inputs before outputs in parameter lists; keep functions short (~80 lines max).
+
+## Documentation
+
+- Document classes and functions with Doxygen JavaDoc-style comments, as in the existing code.
+- Comment tricky/non-obvious code with proper sentences, capitalization, and punctuation.

.github/instructions/ff7-data-formats.instructions.md

@@ -0,0 +1,23 @@
+---
+description: "Use when working on FF7 binary format parsers, serializers, resource managers, LGP/LZS archives, the data installer, or the script decompiler. Covers the File/Serializer/Manager triplet pattern and known installer gotchas."
+applyTo: ["src/data/**", "src/installer/**", "test/data/**", "test/installer/**"]
+---
+
+# FF7 Data Formats and Installer
+
+## Parser Triplet Pattern
+
+Most formats in `src/data/` follow this structure — mirror it when adding formats:
+
+- `XFile` — plain data container for the parsed format.
+- `XFileSerializer` — reads/writes the binary layout (derives from `VGearsSerializer`).
+- `XFileManager` — Ogre `ResourceManager` integration (singleton + `Resource`).
+
+Format documentation lives in [doc/code/FFVII/](../../../doc/code/FFVII/). Check there and at existing similar parsers (e.g. `src/data/worldmap/TxzFile*`) before writing a new one.
+
+## Installer Gotchas (verified, don't regress)
+
+- World map HRC loads must create meshes via `HRCFile::GetMeshFileName()` (i.e. `NameLookup::model(splitBase(hrc_name)) + ".mesh"`). Do NOT use `FF7Data::GetWorldMapModelName()` — that friendly-name table can diverge from the actual Ogre mesh resource name and triggers `FileNotFoundException` (e.g. `barrier.mesh`).
+- `WorldInstaller::ExportMesh()` expects a directory prefix, not a full filename prefix.
+- The decompiler (`src/installer/decompiler/`) emits Lua — keep output close to [doc/STYLE-LUA.md](../../../doc/STYLE-LUA.md), but it is exempt from strict conformance.
+- The installer is Qt-based and handles copyrighted game data at runtime on the user's machine: never write code that copies extracted assets into the repo or build tree.

.github/instructions/lua-style.instructions.md

@@ -0,0 +1,27 @@
+---
+description: "Use when writing or editing Lua scripts (.lua files). V-Gears Lua style: indentation, naming, locals, end terminators, doxygen comments."
+applyTo: "**/*.lua"
+---
+
+# V-Gears Lua Style Essentials
+
+Full guide: [doc/STYLE-LUA.md](../../doc/STYLE-LUA.md).
+
+- Indent with four spaces. Never use tabs.
+- Variables: short `snake_case` (`front_color`); larger scope → more descriptive names.
+- Functions and classes: `PascalCase`. Constants: `ALL_CAPS`. Module names: all `lowercase`.
+- Always use `local` for variables and functions; avoid globals.
+- Always close blocks with `end`; on long blocks, annotate the closing `end` with a comment (`end -- if`).
+- One space after `--` in comments.
+- Document every block of code with doxygen-style docstrings:
+
+```lua
+--[[
+ Retrieves a bit variable.
+ @param bank Memory bank (0-index, as in game).
+ @return 1 or 0
+]]
+```
+
+- Test for non-`nil` idiomatically: `if line then`, not `if line ~= nil then`.
+- Note: Lua generated by the installer's script decompiler follows these rules on a best-effort basis — do not hand-reformat large generated files.

.github/instructions/tests.instructions.md

@@ -0,0 +1,21 @@
+---
+description: "Use when writing, adding, or fixing tests in the test/ directory. Covers Boost.Test conventions, registering test sources in test/CMakeLists.txt, and running the v-gears-tests suite."
+applyTo: "test/**"
+---
+
+# V-Gears Testing Conventions
+
+- Tests use Boost.Test with dynamic linking (`BOOST_TEST_DYN_LINK`); the suite builds as the `v-gears-tests` target and is registered with CTest.
+- Test files mirror the path of the code under test (`test/data/VGearsLGPArchive.cpp` tests `src/data/VGearsLGPArchive.cpp`). Follow this existing convention for placement.
+- Every new test source file must be added manually to `SOURCE_FILES` in [test/CMakeLists.txt](../../test/CMakeLists.txt) — there is no globbing.
+- RTTI (`dynamic_cast`, `typeid`) is allowed in tests even though production code avoids it.
+- Never use original game data in tests. Construct binary fixtures in-code (byte buffers, temp files) instead.
+
+## Running
+
+```bash
+cmake --build build --target v-gears-tests -j$(nproc)
+ctest --test-dir build --output-on-failure
+```
+
+The test binary can also be run directly from the build output directory to filter individual test cases.

.github/prompts/build.prompt.md

@@ -0,0 +1,15 @@
+---
+description: "Configure and build V-Gears with CMake (engine, installer, or test suite)"
+agent: "agent"
+argument-hint: "Optional target or build type, e.g. 'v-gears-installer Release'"
+---
+
+Build the V-Gears project:
+
+1. If no `build/` directory or cache exists, configure first:
+   `cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug`
+   (Use the build type the user asked for, Debug by default. Never build in-tree.)
+2. Build with `cmake --build build -j$(nproc)`, optionally restricted to the requested target (`v-gears`, `v-gears-installer`, `v-gears-tests`).
+3. If compilation fails, read the full error output, fix the root cause following `doc/STYLE.md` and the scoped instructions (C++14 only), and rebuild.
+4. For dependency lookup problems, try `-DUSE_DETERMINISTIC_FALLBACKS=OFF` on a fresh configure to get clean diagnostics before changing any CMake code.
+5. Report the final build status and the location of the produced binaries.

.github/prompts/new-data-format.prompt.md

@@ -0,0 +1,19 @@
+---
+description: "Scaffold a new FF7 data format parser (File/Serializer/Manager triplet) following project conventions"
+agent: "agent"
+argument-hint: "Format name and target directory, e.g. 'XYZ in src/data/worldmap'"
+---
+
+Scaffold a new FF7 binary format parser for the format named by the user:
+
+1. Research first:
+   - Check `doc/code/FFVII/` for documentation of the format.
+   - Read the most similar existing triplet in `src/data/` (e.g. `TxzFile.h/.cpp`, `TxzFileSerializer.h/.cpp`, `TxzFileManager.h/.cpp` in `src/data/worldmap/`) and mirror its structure, base classes, and Doxygen comment style exactly.
+2. Create the triplet in the requested directory:
+   - `XFile` — passive data container for the parsed format.
+   - `XFileSerializer` — binary read/write, deriving from the same serializer base as its neighbors.
+   - `XFileManager` — Ogre `ResourceManager` singleton integration, matching the existing pattern.
+3. Follow `doc/STYLE.md` strictly: C++14, `PascalCase` types, `snake_case` variables with trailing underscore for members, `#pragma once`, correct include order.
+4. Register the new sources in the appropriate `src/CMakeLists.txt` source list (no globbing — add them explicitly, in the same grouped style as neighboring entries).
+5. Do not add or reference original game data; document the binary layout from `doc/code/FFVII/` knowledge in the header comments instead.
+6. Build the affected target to verify it compiles.

.github/prompts/test.prompt.md

@@ -0,0 +1,16 @@
+---
+description: "Build and run the v-gears-tests Boost.Test suite, then diagnose any failures"
+agent: "agent"
+argument-hint: "Optional: specific test case or area to focus on"
+---
+
+Build and run the V-Gears test suite:
+
+1. Build the test target: `cmake --build build --target v-gears-tests -j$(nproc)`
+   (configure `build/` first if it doesn't exist: `cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug`).
+2. Run the suite: `ctest --test-dir build --output-on-failure`.
+3. For each failure, read the failing test and the code under test, fix the root cause, and rerun.
+   - Tests use Boost.Test with dynamic linking.
+   - New test sources must be registered manually in `test/CMakeLists.txt`.
+   - Never use original game data in tests — build fixtures in code.
+4. Report pass/fail counts and summarize what was fixed.