@causyne/agent 0.0.0-stage → 1.10.0

package/src/tools/gameEconomyBalancer.js

@@ -0,0 +1,161 @@
+import fs from 'fs/promises';
+import fsSync from 'fs';
+import path from 'path';
+
+export const gameEconomyBalancer = {
+  schema: {
+    name: 'game.economy_balancer',
+    description: 'Calculates and balances game economy mechanics: enemy stat scaling curves across levels (`enemy_scaling.json`), item drop tables (`loot_tables.json`), item pricing formulas, and player XP/level progression thresholds.',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['balance_enemy_scaling', 'generate_loot_table', 'balance_xp_curve', 'save_economy_data'],
+          description: 'Action: balance_enemy_scaling (compute HP/attack across levels), generate_loot_table (assign drop probabilities), balance_xp_curve (level thresholds), or save_economy_data (write database files).'
+        },
+        maxLevel: { type: 'number', description: 'Maximum player/enemy level to simulate (default 50).' },
+        difficultyCurve: {
+          type: 'string',
+          enum: ['linear', 'exponential', 'souls_hardcore'],
+          description: 'Scaling curve type.'
+        },
+        baseHp: { type: 'number', description: 'Level 1 base HP (default 100).' },
+        baseXp: { type: 'number', description: 'Level 1 base XP required for level 2 (default 500).' },
+        lootEntries: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              item_id: { type: 'string' },
+              drop_chance_pct: { type: 'number' },
+              min_qty: { type: 'number' },
+              max_qty: { type: 'number' }
+            }
+          },
+          description: 'Loot table items and percentage drop chances.'
+        },
+        projectDir: {
+          type: 'string',
+          description: 'Absolute path to project directory (`data/` folder).'
+        }
+      },
+      required: ['action']
+    }
+  },
+
+  async execute(args) {
+    try {
+      const { action, maxLevel = 50, difficultyCurve = 'exponential', baseHp = 100, baseXp = 500, lootEntries = [], projectDir } = args;
+
+      if (action === 'balance_enemy_scaling') {
+        const scalingTable = [];
+        for (let lvl = 1; lvl <= maxLevel; lvl++) {
+          let multiplier = 1.0;
+          if (difficultyCurve === 'linear') {
+            multiplier = 1 + (lvl - 1) * 0.15;
+          } else if (difficultyCurve === 'souls_hardcore') {
+            multiplier = Math.pow(1.22, lvl - 1);
+          } else {
+            // exponential
+            multiplier = Math.pow(1.15, lvl - 1);
+          }
+
+          scalingTable.push({
+            level: lvl,
+            max_hp: Math.round(baseHp * multiplier),
+            attack_damage: Math.round((baseHp * 0.15) * multiplier),
+            xp_reward: Math.round((baseXp * 0.2) * Math.pow(1.12, lvl - 1)),
+            gold_drop: Math.round(15 * Math.pow(1.1, lvl - 1))
+          });
+        }
+
+        if (projectDir && fsSync.existsSync(projectDir)) {
+          const dataDir = path.join(projectDir, 'data');
+          await fs.mkdir(dataDir, { recursive: true });
+          await fs.writeFile(path.join(dataDir, 'enemy_scaling.json'), JSON.stringify(scalingTable, null, 2), 'utf8');
+        }
+
+        return {
+          success: true,
+          output: JSON.stringify({
+            status: 'BALANCED_ENEMY_SCALING',
+            max_level: maxLevel,
+            curve: difficultyCurve,
+            sample_levels: [scalingTable[0], scalingTable[9], scalingTable[24], scalingTable[maxLevel - 1]],
+            total_rows: scalingTable.length
+          }, null, 2)
+        };
+      }
+
+      if (action === 'generate_loot_table') {
+        const table = lootEntries.length > 0 ? lootEntries : [
+          { item_id: 'gold_coins', drop_chance_pct: 85.0, min_qty: 10, max_qty: 45 },
+          { item_id: 'health_potion', drop_chance_pct: 40.0, min_qty: 1, max_qty: 2 },
+          { item_id: 'shadow_shard', drop_chance_pct: 25.0, min_qty: 1, max_qty: 3 },
+          { item_id: 'iron_sword', drop_chance_pct: 8.0, min_qty: 1, max_qty: 1 },
+          { item_id: 'relic_silver_key', drop_chance_pct: 2.5, min_qty: 1, max_qty: 1 }
+        ];
+
+        if (projectDir && fsSync.existsSync(projectDir)) {
+          const dataDir = path.join(projectDir, 'data');
+          await fs.mkdir(dataDir, { recursive: true });
+          await fs.writeFile(path.join(dataDir, 'loot_tables.json'), JSON.stringify({ default_enemy_loot: table }, null, 2), 'utf8');
+        }
+
+        return {
+          success: true,
+          output: JSON.stringify({
+            status: 'GENERATED_LOOT_TABLE',
+            entries_count: table.length,
+            table: table
+          }, null, 2)
+        };
+      }
+
+      if (action === 'balance_xp_curve') {
+        const xpCurve = [];
+        let totalAccumulated = 0;
+        for (let lvl = 1; lvl <= maxLevel; lvl++) {
+          const req = Math.round(baseXp * Math.pow(1.18, lvl - 1));
+          totalAccumulated += req;
+          xpCurve.push({
+            level: lvl,
+            xp_to_next: req,
+            total_xp_required: totalAccumulated
+          });
+        }
+
+        if (projectDir && fsSync.existsSync(projectDir)) {
+          const dataDir = path.join(projectDir, 'data');
+          await fs.mkdir(dataDir, { recursive: true });
+          await fs.writeFile(path.join(dataDir, 'xp_curve.json'), JSON.stringify(xpCurve, null, 2), 'utf8');
+        }
+
+        return {
+          success: true,
+          output: JSON.stringify({
+            status: 'BALANCED_XP_CURVE',
+            max_level: maxLevel,
+            base_xp: baseXp,
+            sample_levels: [xpCurve[0], xpCurve[9], xpCurve[24], xpCurve[maxLevel - 1]]
+          }, null, 2)
+        };
+      }
+
+      if (action === 'save_economy_data') {
+        if (!projectDir || !fsSync.existsSync(projectDir)) {
+          return { success: false, error: `projectDir is required to save economy data.` };
+        }
+        return {
+          success: true,
+          output: JSON.stringify({ status: 'SAVED_ALL_ECONOMY_DATA', project_dir: projectDir }, null, 2)
+        };
+      }
+
+      return { success: false, error: `Unknown action: ${action}` };
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+};

package/src/tools/gameEntitySpawner.js

@@ -0,0 +1,207 @@
+import fs from 'fs/promises';
+import fsSync from 'fs';
+import path from 'path';
+
+export const gameEntitySpawner = {
+  schema: {
+    name: 'game.entity_spawner',
+    description: 'Generates ready-to-instance game entity prefabs (`.tscn` + `.gd` scripts) for Godot 4.x. Includes templates for Player Hero 8-way movement, Skeleton Warrior AI, Boss Necromancer, Cyberpunk Race Car drift physics, Lockable Treasure Chest, and Inter-biome Portal Gate.',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['spawn_prefab', 'list_prefabs', 'batch_spawn_entities'],
+          description: 'Action: spawn_prefab (generate specific prefab .tscn and .gd script), list_prefabs (catalog available entity templates), or batch_spawn_entities (generate all core entities into project).'
+        },
+        prefabType: {
+          type: 'string',
+          enum: ['player_hero_2d', 'player_hero_3d', 'skeleton_warrior_ai', 'boss_necromancer', 'cyberpunk_racer_car', 'treasure_chest', 'portal_gate'],
+          description: 'Type of entity template to generate.'
+        },
+        entityName: {
+          type: 'string',
+          description: 'Custom node name for the spawned entity.'
+        },
+        projectDir: {
+          type: 'string',
+          description: 'Absolute path to Godot project directory (`res://...`) where `scenes/actors` and `scripts/actors` reside.'
+        }
+      },
+      required: ['action']
+    }
+  },
+
+  async execute(args) {
+    try {
+      const { action, prefabType = 'player_hero_2d', entityName, projectDir } = args;
+
+      if (action === 'list_prefabs') {
+        return {
+          success: true,
+          output: JSON.stringify({
+            status: 'PREFAB_CATALOG',
+            prefabs: [
+              { type: 'player_hero_2d', desc: '8-way CharacterBody2D movement with sword attack, dash stamina, and Sprite2D/AnimationPlayer.' },
+              { type: 'player_hero_3d', desc: '3D CharacterBody3D third-person controller with camera springarm and gravity.' },
+              { type: 'skeleton_warrior_ai', desc: 'Melee enemy with patrol/chase/attack AI and loot drop signal.' },
+              { type: 'boss_necromancer', desc: 'Multi-phase boss controller with spell casting and skeleton summoning triggers.' },
+              { type: 'cyberpunk_racer_car', desc: 'Vehicle physics with acceleration, steering drift friction, and nitro boost.' },
+              { type: 'treasure_chest', desc: 'Interactable StaticBody2D/3D with inventory item dispensing signal.' },
+              { type: 'portal_gate', desc: 'Area2D/3D scene transition gate triggering world map changes.' }
+            ]
+          }, null, 2)
+        };
+      }
+
+      if (action === 'spawn_prefab' || action === 'batch_spawn_entities') {
+        const typesToSpawn = action === 'batch_spawn_entities' ? ['player_hero_2d', 'skeleton_warrior_ai', 'treasure_chest', 'portal_gate'] : [prefabType];
+        const results = [];
+
+        for (const pt of typesToSpawn) {
+          const name = entityName || (pt === 'player_hero_2d' ? 'PlayerHero' : pt === 'skeleton_warrior_ai' ? 'SkeletonWarrior' : pt === 'treasure_chest' ? 'TreasureChest' : 'PortalGate');
+          let gdScript = '';
+          let tscnContent = '';
+
+          if (pt === 'player_hero_2d') {
+            gdScript = `extends CharacterBody2D
+
+@export var speed: float = 160.0
+@export var dash_speed: float = 350.0
+var is_attacking: bool = false
+
+@onready var anim: AnimationPlayer = $AnimationPlayer if has_node("AnimationPlayer") else null
+
+func _physics_process(delta: float) -> void:
+\tif is_attacking:
+\t\tvelocity = Vector2.ZERO
+\t\tmove_and_slide()
+\t\treturn
+
+\tvar dir = Input.get_vector("ui_left", "ui_right", "ui_up", "ui_down")
+\tvelocity = dir * speed
+\tmove_and_slide()
+
+\tif Input.is_action_just_pressed("ui_accept") and not is_attacking:
+\t\tattack()
+\telse:
+\t\tif anim:
+\t\t\tif velocity.length() > 10.0:
+\t\t\t\tanim.play("walk")
+\t\t\telse:
+\t\t\t\tanim.play("idle")
+
+func attack() -> void:
+\tis_attacking = true
+\tif anim and anim.has_animation("attack_slash"):
+\t\tanim.play("attack_slash")
+\t\tawait anim.animation_finished
+\tis_attacking = false
+`;
+            tscnContent = `[gd_scene load_steps=2 format=3]
+
+[ext_resource type="Script" path="res://scripts/actors/${name}.gd" id="1_hero"]
+
+[node name="${name}" type="CharacterBody2D" groups=["player"]]
+script = ExtResource("1_hero")
+
+[node name="Sprite2D" type="Sprite2D" parent="."]
+
+[node name="CollisionShape2D" type="CollisionShape2D" parent="."]
+`;
+          } else if (pt === 'skeleton_warrior_ai') {
+            gdScript = `extends CharacterBody2D
+# Skeleton Warrior Enemy AI
+@export var max_hp: float = 100.0
+var current_hp: float
+
+func _ready() -> void:
+\tcurrent_hp = max_hp
+
+func take_damage(amount: float) -> void:
+\tcurrent_hp -= amount
+\tif current_hp <= 0:
+\t\tqueue_free()
+`;
+            tscnContent = `[gd_scene load_steps=2 format=3]
+
+[ext_resource type="Script" path="res://scripts/actors/${name}.gd" id="1_enemy"]
+
+[node name="${name}" type="CharacterBody2D" groups=["enemies"]]
+script = ExtResource("1_enemy")
+`;
+          } else if (pt === 'cyberpunk_racer_car') {
+            gdScript = `extends CharacterBody3D
+# Cyberpunk Highway Race Car Controller
+@export var acceleration: float = 45.0
+@export var max_speed: float = 180.0
+@export var steering_angle: float = 25.0
+var current_speed: float = 0.0
+
+func _physics_process(delta: float) -> void:
+\tvar throttle = Input.get_axis("ui_down", "ui_up")
+\tvar steer = Input.get_axis("ui_right", "ui_left")
+\tcurrent_speed = clamp(current_speed + throttle * acceleration * delta, -30.0, max_speed)
+\trotate_y(deg_to_rad(steer * steering_angle * delta * (current_speed / max_speed)))
+\tvelocity = -transform.basis.z * current_speed
+\tmove_and_slide()
+`;
+            tscnContent = `[gd_scene load_steps=2 format=3]
+
+[ext_resource type="Script" path="res://scripts/actors/${name}.gd" id="1_car"]
+
+[node name="${name}" type="CharacterBody3D" groups=["vehicles"]]
+script = ExtResource("1_car")
+`;
+          } else {
+            // TreasureChest or PortalGate
+            gdScript = `extends Area2D
+signal object_interacted(object_name)
+
+func _on_body_entered(body: Node2D) -> void:
+\tif body.is_in_group("player"):
+\t\tprint("[Entity Interaction] Player interacted with ", name)
+\t\temit_signal("object_interacted", name)
+`;
+            tscnContent = `[gd_scene load_steps=2 format=3]
+
+[ext_resource type="Script" path="res://scripts/actors/${name}.gd" id="1_interact"]
+
+[node name="${name}" type="Area2D"]
+script = ExtResource("1_interact")
+`;
+          }
+
+          if (projectDir && fsSync.existsSync(projectDir)) {
+            const scriptPath = path.join(projectDir, 'scripts/actors', `${name}.gd`);
+            const scenePath = path.join(projectDir, 'scenes/actors', `${name}.tscn`);
+            await fs.mkdir(path.dirname(scriptPath), { recursive: true });
+            await fs.mkdir(path.dirname(scenePath), { recursive: true });
+            await fs.writeFile(scriptPath, gdScript, 'utf8');
+            await fs.writeFile(scenePath, tscnContent, 'utf8');
+            results.push({ prefab: pt, node_name: name, script: scriptPath, scene: scenePath });
+          } else {
+            const tempDir = path.join(process.cwd(), '.tmp_causyne_3d/prefabs');
+            await fs.mkdir(tempDir, { recursive: true });
+            await fs.writeFile(path.join(tempDir, `${name}.gd`), gdScript, 'utf8');
+            await fs.writeFile(path.join(tempDir, `${name}.tscn`), tscnContent, 'utf8');
+            results.push({ prefab: pt, node_name: name, temp_path: tempDir });
+          }
+        }
+
+        return {
+          success: true,
+          output: JSON.stringify({
+            status: 'SPAWNED_PREFABS',
+            project_dir: projectDir || 'temp buffer',
+            entities_created: results
+          }, null, 2)
+        };
+      }
+
+      return { success: false, error: `Unknown action: ${action}` };
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+};

package/src/tools/gameLoreForge.js

@@ -0,0 +1,153 @@
+import fs from 'fs/promises';
+import fsSync from 'fs';
+import path from 'path';
+
+export const gameLoreForge = {
+  schema: {
+    name: 'game.lore_forge',
+    description: 'Generates structured worldbuilding lore, faction histories, biome backstories, and character biographies for RPGs and rich game worlds. Can save directly to project `data/world_lore.json` or return formatted JSON.',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['generate_world_lore', 'generate_character_bio', 'generate_faction', 'save_lore_to_project'],
+          description: 'Action: generate_world_lore (overall setting/history), generate_character_bio (deep NPC/hero backstory), generate_faction (politics/ideology), or save_lore_to_project (persist to JSON).'
+        },
+        title: {
+          type: 'string',
+          description: 'Title of the world, character, or faction (e.g. `Chronicles of Aetheria`, `Archmage Vaelen`, `Shadow Syndicate`).'
+        },
+        genre: {
+          type: 'string',
+          enum: ['medieval_fantasy', 'dark_fantasy', 'cyberpunk', 'sci_fi', 'post_apocalyptic', 'steampunk'],
+          description: 'Genre and tone of the lore.'
+        },
+        keyElements: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'List of key plot devices, relics, biomes, or character traits (e.g. `["The Shadow Relic", "Catacombs", "Betrayed by King"]`).'
+        },
+        projectDir: {
+          type: 'string',
+          description: 'Optional absolute path to Godot/game project directory to save generated lore.'
+        },
+        customLoreData: {
+          type: 'object',
+          description: 'Structured JSON payload to save when action is `save_lore_to_project`.'
+        }
+      },
+      required: ['action', 'title']
+    }
+  },
+
+  async execute(args) {
+    try {
+      const { action, title, genre = 'medieval_fantasy', keyElements = [], projectDir, customLoreData } = args;
+
+      if (action === 'save_lore_to_project') {
+        if (!projectDir || !fsSync.existsSync(projectDir)) {
+          return { success: false, error: `Valid projectDir is required to save lore. Found: ${projectDir}` };
+        }
+        const dataDir = path.join(projectDir, 'data');
+        await fs.mkdir(dataDir, { recursive: true });
+        const filePath = path.join(dataDir, `${title.toLowerCase().replace(/[^a-z0-9]+/g, '_')}_lore.json`);
+        await fs.writeFile(filePath, JSON.stringify(customLoreData || { title, genre, timestamp: Date.now() }, null, 2), 'utf8');
+        return {
+          success: true,
+          output: JSON.stringify({
+            status: 'SAVED_LORE',
+            file_path: filePath,
+            data_size_bytes: fsSync.existsSync(filePath) ? fsSync.statSync(filePath).size : 0
+          }, null, 2)
+        };
+      }
+
+      if (action === 'generate_world_lore') {
+        const loreTemplate = {
+          world_title: title,
+          genre: genre,
+          creation_myth: `In the dawn of ${title}, the primeval forces shaped the continents from ethereal mist and primordial iron. The balance was broken when the ancient relics shattered across the realms.`,
+          core_conflict: keyElements.length > 0 ? `The struggle over ${keyElements.join(', ')} has plunged the kingdoms into perpetual unrest.` : `An ancient darkness stirs beneath the forgotten sanctuaries, threatening to consume all light.`,
+          biomes: [
+            { name: 'Whispering Village', atmosphere: 'Misty, ancient oak groves, rustic thatched taverns under constant twilight.' },
+            { name: 'Forgotten Catacombs', atmosphere: 'Subterranean stone labyrinths guarded by skeletal sentinels and shadow wards.' },
+            { name: 'Shadow Sanctuary', atmosphere: 'Obsidian spires pulsing with void energy and arcane glyphs.' }
+          ],
+          historical_eras: [
+            { era: 'Age of Dawn', description: 'The golden peace where mortals and celestials walked together.' },
+            { era: 'The Great Sundering', description: 'The catastrophic war that buried the Shadow Relic deep beneath the earth.' },
+            { era: 'Age of Shadows (Current)', description: 'A tense era of declining magic and rising necromancy.' }
+          ]
+        };
+
+        if (projectDir && fsSync.existsSync(projectDir)) {
+          const dataDir = path.join(projectDir, 'data');
+          await fs.mkdir(dataDir, { recursive: true });
+          await fs.writeFile(path.join(dataDir, 'world_lore.json'), JSON.stringify(loreTemplate, null, 2), 'utf8');
+        }
+
+        return {
+          success: true,
+          output: JSON.stringify(loreTemplate, null, 2)
+        };
+      }
+
+      if (action === 'generate_character_bio') {
+        const bioTemplate = {
+          character_name: title,
+          genre: genre,
+          archetype: keyElements[0] || 'Vengeful Exile',
+          background: `${title} was once a revered figure in the high court before being cast out due to the conspiracy surrounding ${keyElements.join(' and ') || 'the forbidden shadow arts'}.`,
+          personality_traits: ['Stoic', 'Tactical', 'Haunted by past vows'],
+          combat_style: 'Twin-blade high-velocity strikes combined with shadow displacement spells.',
+          motivations: {
+            primary: 'Reclaim the Shadow Relic and clear their fallen lineage.',
+            secret: 'Prevent the awakening of the Void Sovereign locked within their own soul.'
+          }
+        };
+
+        if (projectDir && fsSync.existsSync(projectDir)) {
+          const dataDir = path.join(projectDir, 'data');
+          await fs.mkdir(dataDir, { recursive: true });
+          await fs.writeFile(path.join(dataDir, `char_${title.toLowerCase().replace(/[^a-z0-9]+/g, '_')}.json`), JSON.stringify(bioTemplate, null, 2), 'utf8');
+        }
+
+        return {
+          success: true,
+          output: JSON.stringify(bioTemplate, null, 2)
+        };
+      }
+
+      if (action === 'generate_faction') {
+        const factionTemplate = {
+          faction_name: title,
+          genre: genre,
+          ideology: 'Preservation through absolute control of arcane artifacts.',
+          headquarters: 'The Obsidian Citadel of Aetheria',
+          key_figures: ['Grand Master Kaelen', 'High Inquisitor Vex'],
+          relations: {
+            player_hero: 'Suspicious / Hostile until loyalty is proven.',
+            shadow_syndicate: 'Mortal enemies locked in clandestine shadow wars.'
+          },
+          resources: ['Shadow Shards', 'Enchanted Steel', 'Ancient Grimoires']
+        };
+
+        if (projectDir && fsSync.existsSync(projectDir)) {
+          const dataDir = path.join(projectDir, 'data');
+          await fs.mkdir(dataDir, { recursive: true });
+          await fs.writeFile(path.join(dataDir, `faction_${title.toLowerCase().replace(/[^a-z0-9]+/g, '_')}.json`), JSON.stringify(factionTemplate, null, 2), 'utf8');
+        }
+
+        return {
+          success: true,
+          output: JSON.stringify(factionTemplate, null, 2)
+        };
+      }
+
+      return { success: false, error: `Unknown action: ${action}` };
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+};

package/src/tools/gameQuestArcBuilder.js

@@ -0,0 +1,152 @@
+import fs from 'fs/promises';
+import fsSync from 'fs';
+import path from 'path';
+
+export const gameQuestArcBuilder = {
+  schema: {
+    name: 'game.quest_arc_builder',
+    description: 'Designs multi-stage quest arcs (Main Story + Side Quests) with prerequisite chains, objective milestones (`kill_enemies`, `collect_items`, `reach_location`), and balanced XP/gold rewards. Outputs production `quest_database.json` suitable for Godot QuestEngine tracking.',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['create_quest_arc', 'add_stage', 'save_quest_db'],
+          description: 'Action: create_quest_arc (build main/side quest series), add_stage (append objective), or save_quest_db (persist database to JSON).'
+        },
+        questId: {
+          type: 'string',
+          description: 'Unique quest identifier (`quest_1_shadow_relic`, `side_quest_iron_blades`).'
+        },
+        questTitle: {
+          type: 'string',
+          description: 'Display title of the quest (`The Shadow Relic`, `Forging the Blade`).'
+        },
+        questType: {
+          type: 'string',
+          enum: ['main_story', 'side_quest', 'daily', 'boss_bounty'],
+          description: 'Category of the quest.'
+        },
+        stages: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              stage_id: { type: 'string' },
+              description: { type: 'string' },
+              objective_type: { type: 'string', enum: ['kill_enemies', 'collect_items', 'reach_location', 'talk_npc', 'interact_object'] },
+              target_id: { type: 'string' },
+              target_count: { type: 'number' }
+            }
+          },
+          description: 'List of quest progression stages.'
+        },
+        rewards: {
+          type: 'object',
+          properties: {
+            xp: { type: 'number' },
+            gold: { type: 'number' },
+            items: { type: 'array', items: { type: 'string' } }
+          },
+          description: 'XP, gold, and item rewards upon completion.'
+        },
+        projectDir: {
+          type: 'string',
+          description: 'Optional absolute path to Godot/game project directory (`res://...`) to save `data/quest_database.json`.'
+        }
+      },
+      required: ['action', 'questId']
+    }
+  },
+
+  async execute(args) {
+    try {
+      const { action, questId, questTitle = 'Quest', questType = 'main_story', stages = [], rewards = { xp: 500, gold: 150, items: ['health_potion'] }, projectDir } = args;
+
+      if (action === 'create_quest_arc') {
+        const defaultStages = stages.length > 0 ? stages : [
+          {
+            stage_id: 'stage_1_elder_counsel',
+            description: 'Speak with Elder Thaddeus in the village square regarding the dark omens.',
+            objective_type: 'talk_npc',
+            target_id: 'village_elder',
+            target_count: 1
+          },
+          {
+            stage_id: 'stage_2_silver_key',
+            description: 'Collect 5 Shadow Shards and trade them to Grom the Blacksmith for the Silver Key.',
+            objective_type: 'collect_items',
+            target_id: 'shadow_shard',
+            target_count: 5
+          },
+          {
+            stage_id: 'stage_3_catacombs_breach',
+            description: 'Pass the ancient wards and enter the Forgotten Catacombs.',
+            objective_type: 'reach_location',
+            target_id: 'level_2_catacombs_entrance',
+            target_count: 1
+          },
+          {
+            stage_id: 'stage_4_skeleton_purge',
+            description: 'Defeat 8 Skeletal Warriors guarding the inner chamber.',
+            objective_type: 'kill_enemies',
+            target_id: 'skeleton_warrior',
+            target_count: 8
+          },
+          {
+            stage_id: 'stage_5_necromancer_showdown',
+            description: 'Vanquish Boss Necromancer Vaelen and claim the Shadow Relic.',
+            objective_type: 'kill_enemies',
+            target_id: 'boss_necromancer',
+            target_count: 1
+          }
+        ];
+
+        const questObject = {
+          quest_id: questId,
+          title: questTitle,
+          type: questType,
+          status: 'available',
+          prerequisites: [],
+          stages: defaultStages,
+          rewards: rewards
+        };
+
+        if (projectDir && fsSync.existsSync(projectDir)) {
+          const dataDir = path.join(projectDir, 'data');
+          await fs.mkdir(dataDir, { recursive: true });
+          const dbPath = path.join(dataDir, 'quest_database.json');
+          let currentDb = {};
+          if (fsSync.existsSync(dbPath)) {
+            try { currentDb = JSON.parse(await fs.readFile(dbPath, 'utf8')); } catch (e) {}
+          }
+          currentDb[questId] = questObject;
+          await fs.writeFile(dbPath, JSON.stringify(currentDb, null, 2), 'utf8');
+        }
+
+        return {
+          success: true,
+          output: JSON.stringify(questObject, null, 2)
+        };
+      }
+
+      if (action === 'save_quest_db') {
+        if (!projectDir || !fsSync.existsSync(projectDir)) {
+          return { success: false, error: `projectDir is required to save quest database.` };
+        }
+        const dataDir = path.join(projectDir, 'data');
+        await fs.mkdir(dataDir, { recursive: true });
+        const dbPath = path.join(dataDir, 'quest_database.json');
+        await fs.writeFile(dbPath, JSON.stringify({ [questId]: { quest_id: questId, title: questTitle, stages, rewards } }, null, 2), 'utf8');
+        return {
+          success: true,
+          output: JSON.stringify({ status: 'SAVED_QUEST_DB', path: dbPath }, null, 2)
+        };
+      }
+
+      return { success: false, error: `Unknown action: ${action}` };
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+};