164 lines
6.8 KiB
Markdown
164 lines
6.8 KiB
Markdown
# 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` files.
|
|
* `GET /api/files/content`: Takes a `filename` query param; returns the parsed JSON content.
|
|
* `POST /api/files/content`: Takes `filename` and `content` (JSON body); writes it back to `resources/definitions/{filename}` with 2-space indentation.
|
|
|
|
**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 JSON file 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<string, IGameRule>`.
|
|
* 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 (`<script setup lang="ts">`), Scoped CSS.
|
|
* **C#:** Namespace `Rules.Generated` for all generated scripts.
|
|
|
|
### 4.3 Safety
|
|
* **No Overwrite:** When creating a new rule, fail if the file already exists.
|
|
* **Backup:** (Bonus) Before saving a JSON file, copy the old version to `tools/ndbs/backups/`.
|
|
|
|
---
|
|
|
|
|
|
## 5. "Get Started" Prompt for AI
|
|
|
|
*To begin implementing this spec, paste the following prompt:*
|
|
|
|
> "I need to initialize the NDBS server as defined in Phase 1 of `specs/numerical_design_system.md`.
|
|
> Please create the directory `tools/ndbs/server`, set up a basic FastAPI `main.py` application, and implement the file listing endpoint `GET /api/files/definitions` that reads from `resources/definitions/`.
|
|
> Use `uvicorn` to run it on port 8000. Ensure CORS is enabled."
|