@soulcraft/kits 1.0.0

package/kits/interactive-fiction/kit.json

@@ -0,0 +1,471 @@
+{
+  "$schema": "https://soulcraft.com/schemas/kit/v2.json",
+  "id": "interactive-fiction",
+  "type": "soulcraft",
+  "role": "primary",
+  "status": "released",
+  "name": "Interactive Fiction",
+  "description": "Build branching narrative games with scenes, choices, and character state",
+  "longDescription": "A browser-based interactive fiction engine built on SvelteKit and Brainy. Design story scenes, build choice branches, track character flags and game state, and play your story in-browser. Brainy stores the entire story graph — characters, scenes, items, and state transitions — so every choice, consequence, and ending lives as a first-class node you can visualise, query, and evolve. Perfect for choose-your-own-adventure, text adventures, and visual novel prototypes.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Soulcraft Labs",
+    "email": "kits@soulcraft.com",
+    "url": "https://soulcraft.com"
+  },
+  "icon": "📖",
+  "tags": [
+    "interactive fiction",
+    "game",
+    "branching narrative",
+    "choose your own adventure",
+    "storytelling",
+    "text adventure",
+    "visual novel"
+  ],
+  "variables": [
+    {
+      "key": "storyTitle",
+      "label": "Story Title",
+      "description": "The title displayed on the cover screen and in the browser tab",
+      "type": "string",
+      "required": true,
+      "example": "The Verdant Labyrinth"
+    },
+    {
+      "key": "storyGenre",
+      "label": "Story Genre",
+      "description": "The genre of your story — sets the AI's default tone and vocabulary",
+      "type": "string",
+      "required": false,
+      "example": "dark fantasy",
+      "default": "adventure"
+    },
+    {
+      "key": "protagonistName",
+      "label": "Protagonist Name",
+      "description": "The default name of the player character (can be overridden at game start)",
+      "type": "string",
+      "required": false,
+      "example": "Kira",
+      "default": "Traveller"
+    },
+    {
+      "key": "startingSceneId",
+      "label": "Starting Scene ID",
+      "description": "The slug of the first scene the player enters when starting a new game",
+      "type": "string",
+      "required": false,
+      "example": "scene-arrival",
+      "default": "scene-start"
+    }
+  ],
+  "shared": {
+    "industry": "games-entertainment",
+    "category": "games",
+    "glossary": {
+      "branch": "A narrative path created by a specific choice — the story follows one branch and ignores others based on what the player picked.",
+      "node": "A scene or decision point in the story graph — every scene and every choice is a node connected by directed edges.",
+      "flag": "A boolean game state variable that records something that happened in the story (e.g. foundKey: true) and can gate future choices or dialogue.",
+      "game state": "The full snapshot of a player's progress — current scene, flags set, items held, and any numeric variables — that persists between sessions.",
+      "consequence": "A change to the world or character that results from a choice, such as gaining an item, triggering a flag, or unlocking a scene.",
+      "dead end": "A scene with no choices and no ending resolution — a design mistake that leaves the player with nowhere to go.",
+      "convergence point": "A scene that multiple branches lead into, used to reunite diverged story paths without duplicating content."
+    },
+    "aiExpertise": [
+      "branching narrative structure and pacing",
+      "character arc design and motivation",
+      "choice consequence design and player agency",
+      "game state management and flag-based gating",
+      "scene writing for interactive media",
+      "dead end detection and story graph repair",
+      "convergence and merge patterns in branching narratives"
+    ],
+    "dataModelHints": [
+      "scene",
+      "choice",
+      "character",
+      "item",
+      "game_state",
+      "ending"
+    ],
+    "dataModel": {
+      "entities": [
+        {
+          "domain": "scene",
+          "type": "Document",
+          "description": "A single moment in the story — descriptive prose, ambient detail, and the set of choices presented to the player. May set or check flags.",
+          "products": {
+            "workshop": {
+              "view": "board",
+              "icon": "🎬"
+            },
+            "academy": {
+              "mapsTo": "learning-artifact",
+              "assessable": true
+            }
+          }
+        },
+        {
+          "domain": "choice",
+          "type": "Event",
+          "description": "A player decision point within a scene. Has display text, a destination scene, optional prerequisites (flags/items), and optional consequences (flag sets, item grants).",
+          "products": {
+            "workshop": {
+              "view": "graph",
+              "icon": "🔀"
+            },
+            "academy": {
+              "mapsTo": "practice-session",
+              "assessable": true
+            }
+          }
+        },
+        {
+          "domain": "character",
+          "type": "Person",
+          "description": "A story character — protagonist, NPC, or antagonist — with a name, description, traits, and optional stat block. Tracks items held.",
+          "products": {
+            "workshop": {
+              "view": "gallery",
+              "icon": "🧑"
+            },
+            "academy": {
+              "mapsTo": "learner",
+              "assessable": false
+            }
+          }
+        },
+        {
+          "domain": "item",
+          "type": "Thing",
+          "description": "An object a character can hold, use, or give. May unlock choices or scenes when present in the player's inventory.",
+          "products": {
+            "workshop": {
+              "view": "gallery",
+              "icon": "🎒"
+            }
+          }
+        },
+        {
+          "domain": "game_state",
+          "type": "Concept",
+          "description": "A snapshot of all flags and variables at a given point in the story. Used to gate choices and unlock conditional scenes.",
+          "products": {
+            "workshop": {
+              "view": "graph",
+              "icon": "⚙️"
+            },
+            "academy": {
+              "mapsTo": "knowledge-unit",
+              "assessable": false
+            }
+          }
+        },
+        {
+          "domain": "ending",
+          "type": "Document",
+          "description": "A story conclusion — good, bad, or neutral — that terminates the game loop and presents a final message. Links back to the flags and choices that led to it.",
+          "products": {
+            "workshop": {
+              "view": "board",
+              "icon": "🏁"
+            },
+            "academy": {
+              "mapsTo": "learning-artifact",
+              "assessable": true
+            }
+          }
+        }
+      ],
+      "relationships": [
+        {
+          "from": "scene",
+          "to": "choice",
+          "verb": "Contains",
+          "description": "Scene presents one or more choices to the player."
+        },
+        {
+          "from": "choice",
+          "to": "scene",
+          "verb": "LeadsTo",
+          "description": "Choice navigates the player to the destination scene when selected."
+        },
+        {
+          "from": "character",
+          "to": "item",
+          "verb": "Holds",
+          "description": "Character carries an item in their inventory that may unlock choices or scenes."
+        },
+        {
+          "from": "scene",
+          "to": "game_state",
+          "verb": "Modifies",
+          "description": "Scene sets, clears, or checks game state flags when entered or exited."
+        },
+        {
+          "from": "choice",
+          "to": "game_state",
+          "verb": "Modifies",
+          "description": "Choice sets consequences — flags or item grants — that alter game state when taken."
+        },
+        {
+          "from": "scene",
+          "to": "character",
+          "verb": "References",
+          "description": "Scene features one or more characters through dialogue, description, or interaction."
+        }
+      ]
+    },
+    "suggestions": [
+      {
+        "label": "Write a scene",
+        "prompt": "Help me write a new story scene with descriptive prose and two or three meaningful choices."
+      },
+      {
+        "label": "Design a choice",
+        "prompt": "Help me design a choice that has a clear good option, a risky option, and a deceptive-looking bad option."
+      },
+      {
+        "label": "Map the story graph",
+        "prompt": "Show me the current story graph — all scenes and how they connect through choices."
+      },
+      {
+        "label": "Check for dead ends",
+        "prompt": "Analyse the story graph and flag any scenes with no choices and no ending resolution."
+      },
+      {
+        "label": "Add a character",
+        "prompt": "Help me create a new supporting character with a name, motivation, and distinctive voice."
+      },
+      {
+        "label": "Design an ending",
+        "prompt": "Help me write a satisfying ending for the path where the protagonist makes all the right choices."
+      }
+    ]
+  },
+  "academy": {
+    "skillPath": "game-design",
+    "level": "intermediate",
+    "learningObjectives": [
+      "Design a branching narrative structure with clear story beats, meaningful branches, and multiple endings",
+      "Write scenes with evocative prose that establishes tone and gives the player genuine agency",
+      "Track character and world state using flags and variables to gate choices believably",
+      "Identify and resolve dead ends, loops, and pacing problems in the story graph",
+      "Build a complete playable story from opening scene through all major branches to resolved endings"
+    ],
+    "assessmentTypes": [
+      "demo",
+      "portfolio"
+    ],
+    "certificationSlug": "fiction-game-designer"
+  },
+  "workshop": {
+    "difficulty": "intermediate",
+    "templateTier": 4,
+    "aiPersona": {
+      "role": "You are a narrative game designer helping creators build compelling branching stories with meaningful choices and satisfying endings. You understand story structure, player agency, and the technical constraints of flag-based game state.",
+      "expertise": [
+        "branching narrative structure and pacing",
+        "character arc design and motivation",
+        "choice consequence design and player agency",
+        "game state management and flag-based gating",
+        "scene writing for interactive media",
+        "dead end detection and story graph repair",
+        "convergence and merge patterns in branching narratives"
+      ],
+      "tone": "collaborator",
+      "avoidances": [
+        "Don't write choices that are obviously correct — every option should feel like a real decision",
+        "Don't let the graph grow so wide that maintaining continuity becomes impossible — recommend convergence points",
+        "Don't write more flags than the story actually needs — unnecessary state is a maintenance burden"
+      ]
+    },
+    "workspaceConfig": {
+      "paradigm": "creative",
+      "defaultTab": "app",
+      "defaultView": "graph"
+    },
+    "graphGuidance": {
+      "conceptCreation": {
+        "triggers": [
+          "new scene or location described",
+          "player choice or decision point designed",
+          "character introduced or named",
+          "item or inventory object mentioned",
+          "story ending or resolution written",
+          "flag or game state variable defined"
+        ],
+        "typeMapping": {
+          "scene": "document",
+          "location": "document",
+          "choice": "event",
+          "decision": "event",
+          "character": "person",
+          "protagonist": "person",
+          "npc": "person",
+          "item": "thing",
+          "object": "thing",
+          "ending": "document",
+          "game state": "concept",
+          "flag": "concept"
+        }
+      },
+      "relationshipPatterns": [
+        {
+          "from": "scene",
+          "to": "choice",
+          "verb": "Contains",
+          "description": "Scene presents choices to the player"
+        },
+        {
+          "from": "choice",
+          "to": "scene",
+          "verb": "LeadsTo",
+          "description": "Choice takes the player to the destination scene"
+        },
+        {
+          "from": "character",
+          "to": "item",
+          "verb": "Holds",
+          "description": "Character carries item in inventory"
+        }
+      ],
+      "rules": [
+        "Every scene (except endings) must have at least one choice connected to another scene",
+        "Every ending must have at least one choice that leads into it",
+        "Flag nodes should be reused across scenes — one flag, many references",
+        "Items must be linked to the character that holds them before they can gate a choice"
+      ]
+    },
+    "qualityGates": {
+      "projectChecks": [
+        "App starts and the starting scene loads correctly",
+        "Player can make a choice and navigate to the destination scene",
+        "At least one flag is set by a choice and checked by a later scene",
+        "At least one item exists and gates a player choice",
+        "At least one ending scene is reachable via a complete play-through",
+        "No dead-end scenes exist in the graph"
+      ],
+      "exportReady": [
+        "No TypeScript errors",
+        "All scenes have prose and at least one choice or an ending resolution",
+        "Story is completable from start to at least one ending"
+      ]
+    },
+    "templateMetadata": {
+      "identifyByStructure": true,
+      "runnable": true,
+      "runnableCommand": "npm run dev"
+    },
+    "deploy": {
+      "provider": "cloud-run",
+      "buildCommand": "npm run build",
+      "outputDir": "build",
+      "config": {
+        "port": 3000,
+        "memory": "256Mi"
+      },
+      "oneClickCommand": "gcloud run deploy"
+    },
+    "publishConfig": {
+      "contentType": "app",
+      "publishable": true
+    },
+    "sampleData": {
+      "description": "A starter story with two scenes, three choices, and one branching path to demonstrate the engine",
+      "entities": [
+        {
+          "type": "person",
+          "name": "The Traveller",
+          "properties": {
+            "role": "protagonist",
+            "description": "A wanderer who has arrived at the edge of the Verdant Labyrinth with nothing but a worn map and a question.",
+            "traits": [
+              "curious",
+              "cautious"
+            ]
+          }
+        },
+        {
+          "type": "document",
+          "name": "The Gate",
+          "properties": {
+            "sceneId": "scene-start",
+            "prose": "You stand before a gate of twisted iron, overgrown with luminous moss. Two paths split before you — the wide road to the left, and a narrow gap in the hedge to the right. A crow watches from the arch above.",
+            "status": "published"
+          }
+        },
+        {
+          "type": "event",
+          "name": "Take the wide road",
+          "properties": {
+            "choiceText": "Take the wide road",
+            "destinationSceneId": "scene-road",
+            "consequence": null
+          }
+        },
+        {
+          "type": "thing",
+          "name": "Worn Map",
+          "properties": {
+            "description": "A folded map with faded annotations. One corner shows a landmark labelled 'the hollow oak'.",
+            "acquiredAt": "scene-start"
+          }
+        }
+      ],
+      "relationships": [
+        {
+          "from": "The Gate",
+          "verb": "Contains",
+          "to": "Take the wide road"
+        },
+        {
+          "from": "The Traveller",
+          "verb": "Holds",
+          "to": "Worn Map"
+        }
+      ]
+    },
+    "remoteWorkspace": {
+      "connectedWorkbenches": [
+        {
+          "name": "Story Graph",
+          "view": "graph",
+          "entityTypes": [
+            "scene",
+            "choice",
+            "ending"
+          ],
+          "description": "Visual map of every scene and how choices connect them"
+        },
+        {
+          "name": "Scene Editor",
+          "view": "board",
+          "entityTypes": [
+            "scene",
+            "ending"
+          ],
+          "description": "Browse and edit scenes with their prose and choice lists"
+        },
+        {
+          "name": "Character & Item Roster",
+          "view": "gallery",
+          "entityTypes": [
+            "character",
+            "item"
+          ],
+          "description": "All characters and inventory items with their current holders"
+        },
+        {
+          "name": "Game State Flags",
+          "view": "stats",
+          "entityTypes": [
+            "game_state"
+          ],
+          "description": "All flags defined in the story with which scenes set and check them"
+        }
+      ]
+    }
+  }
+}