# Numerical Design & Balancing System (NDBS) - Implementation Guide **Version:** 2.0 (AI-Actionable) **Target Stack:** Python (FastAPI), Vue.js (Vite), C# (Godot .NET) **Role:** AI Developer Guide ## 1. System Overview The NDBS is a local web application enabling game designers to: 1. **Edit Game Data:** Modify JSON files in `resources/definitions/` (Traits, Archetypes, Items) via a GUI. 2. **Script Logic:** Write C# code for `RuleIds` (special game logic) in a browser-based IDE. The system auto-generates the corresponding `.cs` files in `scripts/Rules/Generated/`. This guide is structured as a sequence of tasks for an AI agent to implement the system incrementally. --- ## 2. Directory Structure Plan The tool will reside in a new `tools/ndbs/` directory, keeping it separate from the game assets but with access to them. ```text D:\code\super-mentor\ ├── resources\definitions\ <-- Target Data Source ├── scripts\Rules\Generated\ <-- Target Script Output ├── tools\ │ └── ndbs\ │ ├── server\ <-- Python Backend │ │ ├── main.py │ │ └── ... │ └── client\ <-- Vue Frontend │ ├── src\ │ └── ... ``` --- ## 3. Implementation Phases (AI Prompts) ### Phase 1: Python Backend Foundation **Goal:** Establish a FastAPI server that can read/write the game's JSON files. **Step 1.1: Environment Setup** * **Instruction:** Create `tools/ndbs/server/`. Initialize a Python environment. Install `fastapi`, `uvicorn`, `pydantic`. * **Code Requirement:** Create `tools/ndbs/server/main.py`. * **Key Functionality:** * Enable CORS (allow all origins for dev). * Define a constant `PROJECT_ROOT` pointing to `../../../../`. **Step 1.2: File System API** * **Instruction:** Implement endpoints to list and read definitions. * **Endpoints:** * `GET /api/files/definitions`: Scans `resources/definitions/` and returns a list of `.json` AND `.tres` files. * `GET /api/files/content`: Takes a `filename` query param. * If `.json`: Returns parsed JSON. * If `.tres`: Parses the `[resource]` section key-value pairs into a JSON object. Handles arrays (e.g., `Tags = [ "a", "b" ]`) and strings. * `POST /api/files/content`: Takes `filename` and `content` (JSON body). * If `.json`: Writes standard JSON. * If `.tres`: Reads the original file, replaces the values in the `[resource]` section with new values from the JSON, and saves preserving the header/metadata. **Step 1.3: Schema Inference (Dynamic Models)** * **Instruction:** Since we don't have hardcoded Pydantic models for every file, create a utility that reads a file (JSON or TRES) and generates a generic "Schema" description (listing keys and value types) to help the frontend build forms dynamically. --- ### Phase 2: Vue.js Frontend Foundation **Goal:** A clean UI to browse files and edit JSON data. **Step 2.1: Project Scaffolding** * **Instruction:** Create `tools/ndbs/client` using Vite + Vue 3 (TypeScript). Install `axios`, `pinia` (state management), and `naive-ui` (or `element-plus`) for UI components. **Step 2.2: File Explorer & Layout** * **Instruction:** Create a standard "Sidebar + Main Content" layout. * **Sidebar:** Fetches the list of files from `GET /api/files/definitions` and displays them as a menu. * **Main Content:** A RouterView to show the editor. **Step 2.3: Generic JSON Editor** * **Instruction:** Create a component `JsonEditor.vue`. * Fetch content using `GET /api/files/content`. * Display the raw JSON in a textarea (Monaco Editor preferred later, start simple). * Add a "Save" button that calls `POST /api/files/content`. * **Enhancement:** Use a library like `jsoneditor` or `v-jsoneditor` to provide a tree view/form view. --- ### Phase 3: C# Rule Engine Integration (Godot Side) **Goal:** Prepare the game code to dynamically load the scripts we will generate later. **Step 3.1: Define the Interface** * **Instruction:** Create `scripts/Core/Interfaces/IGameRule.cs`. ```csharp namespace Core.Interfaces; using Models; public interface IGameRule { string Id { get; } // Example hooks - adjust based on GameSystems.cs analysis void OnEvent(GameSession session, object gameEvent); void ModifyStats(UnitModel unit, StatRequest request); } ``` **Step 3.2: Rule Manager (The Loader)** * **Instruction:** Create `scripts/Core/Systems/RuleManager.cs`. * Use **Reflection** to find all classes implementing `IGameRule`. * Store them in a `Dictionary`. * Provide a method `ExecuteRule(string ruleId, ...)` that looks up the rule and calls its methods. **Step 3.3: Hook into Game Systems** * **Instruction:** Modify `scripts/Core/GameSystems.cs` (specifically `SynergySystem` or `TaskSystem`). * Find where `RuleIds` are iterated. * Inject a call to `RuleManager.Instance.ExecuteRule(ruleId, ...)` inside those loops. --- ### Phase 4: Scriptable Rule Editor (Full Stack) **Goal:** Allow creating new C# rules from the web UI. **Step 4.1: Backend - Template Generator** * **Instruction:** Add endpoint `POST /api/rules/create`. * **Params:** `rule_id` (e.g., "grinder_stress_effect"). * **Action:** 1. Validate naming (alphanumeric). 2. Load a C# template string (Class name = `Rule_{CamelCaseId}`). 3. Write file to `scripts/Rules/Generated/Rule_{CamelCaseId}.cs`. 4. Return success. **Step 4.2: Frontend - C# Editor** * **Instruction:** Add a "Rules" section to the sidebar. * List `.cs` files in `scripts/Rules/Generated/` (add backend endpoint for this). * Integrate **Monaco Editor** (Vue wrapper) for syntax highlighting. * Save button writes the C# content back to disk. **Step 4.3: Compilation Trigger (Optional but Recommended)** * **Instruction:** Add a "Verify" button. * Backend endpoint `POST /api/build`. * Runs `dotnet build` shell command. * Returns stdout/stderr to the frontend console. --- ## 4. Technical Constraints & Conventions ### 4.1 File Paths * **Server Root:** `tools/ndbs/server` * **Client Root:** `tools/ndbs/client` * **Game Root:** `../../` (Relative to server) ### 4.2 Coding Style * **Python:** Type hints (Python 3.10+), Pydantic models for request/response bodies. * **Vue:** Composition API (`