diff --git a/agents.md b/agents.md new file mode 100644 index 0000000..7027398 --- /dev/null +++ b/agents.md @@ -0,0 +1,236 @@ +WallCraft AI Agents Collaboration Guide for WallCraft AI + +Overview +- Purpose: Define how automated agents will plan, explore, and assist in building a cloud-driven AI workflow for FoundryVTT scene prep (walls, doors, windows), with a safe preview-first workflow. +- Scope: Plan, explore, and coordinate tasks across agent types; no direct code edits by agents, only plan and guidance unless explicitly executed by humans. + +Agent Roles and Responsibilities +- General Planner (PlanAgent) + - Create high-level task plans, decompose features into concrete steps, and assign ownership. +- Explorer (ExploreAgent) + - Inspect repository structure, FoundryVTT APIs, and proposed module architecture. +- Code Searcher (CodesearchAgent) + - Look up API docs, FoundryVTT wall/scene data models, and related examples. +- Web Scout (WebSearchAgent) + - Retrieve current best practices, security considerations, and external docs relevant to cloud AI integration and similar Foundry workflows. + +Interaction Protocol +- Requests and responses are exchanged as structured JSON envelopes. +- Each task has: task_id, objective, inputs, constraints, and expected outputs. +- All agents should statically log their actions to an in-app log or a dedicated journal entry for traceability. + +Example envelope (high-level) +- Plan request + { + "task_id": "plan-001", + "role": "Planner", + "objective": "Define MVP milestones for AI Prep pipeline", + "inputs": { "scope": "FoundryVTT 13.0.351 MVP" }, + "constraints": { "no destructive edits during planning": true } + } +- Plan response + { + "status": "ok", + "task_id": "plan-001", + "plan": [ + "Create module scaffold with manifest.json", + "Implement Settings for cloud endpoint and provider", + "Add AI Prep UI (Scene toolbar) and preview layer", + "Define payload schema and fixed prompt template", + "Implement preview → manual adjust → apply workflow", + "Add logging and minimal docs" + ], + "notes": "Keep MVP strictly non-destructive during preview; apply only after explicit confirmation." + } + +Task Lifecycle and Phases +- Phase 0: Planning and scoping +- Phase 1: MVP scaffolding (module skeleton, settings, UI hooks) +- Phase 2: Cloud integration and preview rendering +- Phase 3: Apply flow (convert AI walls to Foundry walls) +- Phase 4: Safety, validation, and docs +- Phase 5: Optional enhancements (Doors/Windows refine, per-scene prompts, etc.) + +Data Exchange and Contracts (see data-contracts.md) +- Use a fixed, provider-agnostic payload to cloud AI endpoint +- Validate AI responses against Foundry grid constraints before enabling apply + +Quality and Safety +- Preview is mandatory before applying changes +- All actions should be auditable (chat log or journal entry) +- Validate that walls align to grid and do not collide with tokens +- Optional data redaction in settings for privacy-sensitive scenes + +Documentation and Handoff +- Produce a short design doc, an API contract summary, and a quick-start guide +- Maintain change logs for major iterations and provider changes + +4) data-contracts.md +AI Prep Data Contracts (Input to AI, and AI Output) + +Input payload to cloud AI +- Schema (JSON) + { + "scene": { "id": "scene123", "name": "Test Scene" }, + "gridSize": 32, + "walls": [ + { "c": [1,1,5,1], "type": "wall", "notes": "outer boundary" }, + { "c": [5,1,5,5], "type": "door", "notes": "entry" } + ], + "tokens": [ + { "id": "tok1", "x": 3, "y": 3, "w": 1, "h": 1 } + ], + "promptTemplate": "Fixed MVP prompt template string", + "providerMetadata": { "providerName": "OpenCodeCloud", "version": "v1" }, + "previewOnly": true + } + +AI output payload +- Schema (JSON) + { + "walls": [ + { "c": [1,1,6,1], "type": "wall", "notes": "perimeter suggestion" }, + { "c": [6,1,6,6], "type": "door", "notes": "future entry" } + ], + "notes": [ "Preview generated" ], + "validationHints": [ "Walls may cross token area; adjust endpoints" ], + "previewOnly": true + } + +Notes +- All coordinates are grid-aligned integers. +- Unknown fields from provider can be ignored by the client. +- If previewOnly is true, apply is disabled until user explicitly enables it. + +5) api-contract.md +Cloud AI Endpoint Contract (example) + +Endpoint +- POST https://api.youraihost.com/ai/map-prep + +Headers +- Authorization: Bearer +- Content-Type: application/json + +Request body (see data-contracts.md) +- { + "scene": { "id": "...", "name": "..." }, + "gridSize": 32, + "walls": [...], + "tokens": [...], + "promptTemplate": "...", + "providerMetadata": { "providerName": "...", "version": "..." }, + "previewOnly": true + } + +Response +- 200 OK + - { + "walls": [...], + "notes": ["Preview generated"], + "validationHints": [...], + "previewOnly": true + } +- 4xx/5xx responses + - { "error": "invalid_payload", "message": "..." } + - { "error": "auth_failed", "message": "Invalid API token" } + +Security and Privacy +- Use HTTPS; support short-lived tokens +- Minimize data; avoid sending unrelated scene data unless required +- Log access on the server side; provide per-request trace IDs + +6) onboarding.md +Onboarding for WallCraft AI Contributors + +Overview +- This document helps new contributors get up to speed on the WallCraft AI MVP project. + +Getting started +- Prerequisites: FoundryVTT v13.0.351, node environment for building modules, access to cloud AI endpoint +- Repository layout: modules/wallcraft-ai/ with module.json and src/ +- Key files to know: + - module.json: module manifest + - src/AIPrep.js: main module entry + - src/AIEndpoint.js: HTTP client for cloud AI + - src/PreviewLayer.js: canvas overlay logic + - src/SettingsPanel.js: UI to configure endpoint/token/provider + - src/UIFlow.js: dialog and adjustment UI + +Development workflow +- Plan first: use agents.md to outline tasks +- Implement in small, testable increments +- Use non-destructive previews first; require explicit apply +- Write minimal tests or manual checks for payload shaping and wall conversion + +Conventions +- Naming: consistent with FoundryVTT APIs (Wall, Door, Window, Scene) +- Data models: grid-aligned coordinates, tokens as bounding boxes +- Logging: messages go to chat or a dedicated journal entry + +Testing and validation +- Manual test plan: create a sample scene, run AI Prep, verify preview, adjust, apply, verify persistence +- Edge cases: empty AI response, missing fields, invalid coordinates + +Deployment and updates +- Document how to deploy updates to cloud endpoint if users host their own +- Provide migration notes for API changes (backward compatibility guidance) + +7) glossary.md +WallCraft AI Glossary + +- FoundryVTT: The virtual tabletop platform being extended. +- Scene: A map/workspace in FoundryVTT where walls, tokens, and other elements live. +- Wall: A linear obstacle segment; may be solid, a door, or a window. +- Door/Window: Wall segments with special types; may require swing/hinge data later. +- GridSize: The pixel size of a single tile on the scene grid. +- Preview: A non-destructive overlay showing AI-suggested walls before applying them. +- MVP: Minimum Viable Product. +- API Token: Secret used to authorize requests to the cloud AI endpoint. + +8) quick-start.md +WallCraft AI Quick Start (MVP) + +What you’ll get +- A cloud-driven FoundryVTT MVP to generate walls (including doors/windows) for the current scene. +- Non-destructive preview with manual adjustments before applying. + +Setup +- Install FoundryVTT module (WallCraft AI) for FoundryVTT v13.0.351 +- Configure cloud endpoint URL and API token in Settings +- Ensure the cloud AI endpoint is reachable via HTTPS + +How to use +- In FoundryVTT, open a scene and click the WallCraft AI Prep button in the Scene toolbar +- The module collects scene data and sends a fixed prompt to the cloud AI +- See a translucent preview of AI-generated walls +- Use the adjustment panel to tweak endpoints or types if needed +- Click Apply to persist walls to the scene +- Review chat/journal log for traceability + +Notes +- Batching and multi-scene processing are not part of MVP; plan for future sprints if you want to scale. +- Security: only necessary scene data is sent; token remains with you. + +Next steps +- If you’d like, I can generate concrete starter patches (module.json + a minimal AIPrep.js skeleton and the SettingsPanel), plus the exact payload shapes ready to patch into your repo. I can also tailor naming and endpoint paths to your preferred conventions. + +9) structure.md +WallCraft AI – Default File Structure + +- /modules/wallcraft-ai/ + - module.json + - /src/ + - AIPrep.js + - AIEndpoint.js + - PreviewLayer.js + - SettingsPanel.js + - UIFlow.js + - /agents.md + - /data-contracts.md + - /api-contract.md + - /onboarding.md + - /glossary.md + - /quick-start.md + +This structure keeps the core module logic separated from the documentation and keeps the docs versioned with the module code. diff --git a/api-contract.md b/api-contract.md new file mode 100644 index 0000000..a21cffc --- /dev/null +++ b/api-contract.md @@ -0,0 +1,36 @@ +Cloud AI Endpoint Contract (example) + +Endpoint +- POST https://api.youraihost.com/ai/map-prep + +Headers +- Authorization: Bearer +- Content-Type: application/json + +Request body (see data-contracts.md) +- { + "scene": { "id": "...", "name": "..." }, + "gridSize": 32, + "walls": [...], + "tokens": [...], + "promptTemplate": "...", + "providerMetadata": { "providerName": "...", "version": "..." }, + "previewOnly": true + } + +Response +- 200 OK + - { + "walls": [...], + "notes": ["Preview generated"], + "validationHints": [...], + "previewOnly": true + } +- 4xx/5xx responses + - { "error": "invalid_payload", "message": "..." } + - { "error": "auth_failed", "message": "Invalid API token" } + +Security and Privacy +- Use HTTPS; support short-lived tokens +- Minimize data; avoid sending unrelated scene data unless required +- Log access on the server side; provide per-request trace IDs diff --git a/data-contracts.md b/data-contracts.md new file mode 100644 index 0000000..2f71113 --- /dev/null +++ b/data-contracts.md @@ -0,0 +1,35 @@ +AI Prep Data Contracts (Input to AI, and AI Output) + +Input payload to cloud AI +- Schema (JSON) + { + "scene": { "id": "scene123", "name": "Test Scene" }, + "gridSize": 32, + "walls": [ + { "c": [1,1,5,1], "type": "wall", "notes": "outer boundary" }, + { "c": [5,1,5,5], "type": "door", "notes": "entry" } + ], + "tokens": [ + { "id": "tok1", "x": 3, "y": 3, "w": 1, "h": 1 } + ], + "promptTemplate": "Fixed MVP prompt template string", + "providerMetadata": { "providerName": "OpenCodeCloud", "version": "v1" }, + "previewOnly": true + } + +AI output payload +- Schema (JSON) + { + "walls": [ + { "c": [1,1,6,1], "type": "wall", "notes": "perimeter suggestion" }, + { "c": [6,1,6,6], "type": "door", "notes": "future entry" } + ], + "notes": [ "Preview generated" ], + "validationHints": [ "Walls may cross token area; adjust endpoints" ], + "previewOnly": true + } + +Notes +- All coordinates are grid-aligned integers. +- Unknown fields from provider can be ignored by the client. +- If previewOnly is true, apply is disabled until user explicitly enables it. diff --git a/glossary.md b/glossary.md new file mode 100644 index 0000000..6ca9a7c --- /dev/null +++ b/glossary.md @@ -0,0 +1,10 @@ +WallCraft AI Glossary + +- FoundryVTT: The virtual tabletop platform being extended. +- Scene: A map/workspace in FoundryVTT where walls, tokens, and other elements live. +- Wall: A linear obstacle segment; may be solid, a door, or a window. +- Door/Window: Wall segments with special types; may require swing/hinge data later. +- GridSize: The pixel size of a single tile on the scene grid. +- Preview: A non-destructive overlay showing AI-suggested walls before applying them. +- MVP: Minimum Viable Product. +- API Token: Secret used to authorize requests to the cloud AI endpoint. diff --git a/module.json b/module.json new file mode 100644 index 0000000..0fc871e --- /dev/null +++ b/module.json @@ -0,0 +1,19 @@ +{ + "name": "wallcraft-ai", + "title": "WallCraft AI", + "description": "Cloud-driven, provider-agnostic AI prep for FoundryVTT scenes (walls including doors and windows) with a safe preview-first workflow.", + "version": "0.1.0", + "author": "OpenCode", + "minimumCoreVersion": "13.0.0", + "compatibleCoreVersion": "13.*", + "esmodules": true, + "scripts": [ + "src/AIPrep.js", + "src/AIEndpoint.js", + "src/PreviewLayer.js", + "src/SettingsPanel.js", + "src/UIFlow.js" + ], + "url": "https://example.com/wallcraft-ai", + "license": "MIT" +} diff --git a/onboarding.md b/onboarding.md new file mode 100644 index 0000000..843e945 --- /dev/null +++ b/onboarding.md @@ -0,0 +1,34 @@ +Onboarding for WallCraft AI Contributors + +Overview +- This document helps new contributors get up to speed on the WallCraft AI MVP project. + +Getting started +- Prerequisites: FoundryVTT v13.0.351, node environment for building modules, access to cloud AI endpoint +- Repository layout: modules/wallcraft-ai/ with module.json and src/ +- Key files to know: + - module.json: module manifest + - src/AIPrep.js: main module entry + - src/AIEndpoint.js: HTTP client for cloud AI + - src/PreviewLayer.js: canvas overlay logic + - src/SettingsPanel.js: UI to configure endpoint/token/provider + - src/UIFlow.js: dialog and adjustment UI + +Development workflow +- Plan first: use agents.md to outline tasks +- Implement in small, testable increments +- Use non-destructive previews first; require explicit apply +- Write minimal tests or manual checks for payload shaping and wall conversion + +Conventions +- Naming: consistent with FoundryVTT APIs (Wall, Door, Window, Scene) +- Data models: grid-aligned coordinates, tokens as bounding boxes +- Logging: messages go to chat or a dedicated journal entry + +Testing and validation +- Manual test plan: create a sample scene, run AI Prep, verify preview, adjust, apply, verify persistence +- Edge cases: empty AI response, missing fields, invalid coordinates + +Deployment and updates +- Document how to deploy updates to cloud endpoint if users host their own +- Provide migration notes for API changes (backward compatibility guidance) diff --git a/progress-todos.json b/progress-todos.json new file mode 100644 index 0000000..fe51488 --- /dev/null +++ b/progress-todos.json @@ -0,0 +1 @@ +[] diff --git a/progress.json b/progress.json new file mode 100644 index 0000000..779a305 --- /dev/null +++ b/progress.json @@ -0,0 +1,12 @@ +[ + {"id":"t-1","content":"Initialize module skeleton (module.json) and scaffolding","status":"in_progress","priority":"high"}, + {"id":"t-2","content":"Implement SettingsPanel for endpoint/token/provider","status":"pending","priority":"high"}, + {"id":"t-3","content":"Implement AIPrep.js to collect scene data and build payload","status":"pending","priority":"high"}, + {"id":"t-4","content":"Implement AIEndpoint.js to call cloud API and handle responses","status":"pending","priority":"high"}, + {"id":"t-5","content":"Implement PreviewLayer.js for non-destructive previews","status":"pending","priority":"high"}, + {"id":"t-6","content":"Implement UIFlow.js to drive MVP flow","status":"pending","priority":"medium"}, + {"id":"t-7","content":"Wire up Apply logic to convert AI walls to Foundry walls","status":"pending","priority":"high"}, + {"id":"t-8","content":"Create documentation: quick-start, data/api contracts","status":"pending","priority":"medium"}, + {"id":"t-9","content":"Add basic tests/manual validation plan","status":"pending","priority":"medium"}, + {"id":"t-10","content":"Polish error handling, security notes","status":"pending","priority":"low"} +] diff --git a/quick-start.md b/quick-start.md new file mode 100644 index 0000000..d91e3fd --- /dev/null +++ b/quick-start.md @@ -0,0 +1,25 @@ +WallCraft AI Quick Start (MVP) + +What you’ll get +- A cloud-driven FoundryVTT MVP to generate walls (including doors/windows) for the current scene. +- Non-destructive preview with manual adjustments before applying. + +Setup +- Install FoundryVTT module (WallCraft AI) for FoundryVTT v13.0.351 +- Configure cloud endpoint URL and API token in Settings +- Ensure the cloud AI endpoint is reachable via HTTPS + +How to use +- In FoundryVTT, open a scene and click the WallCraft AI Prep button in the Scene toolbar +- The module collects scene data and sends a fixed prompt to the cloud AI +- See a translucent preview of AI-generated walls +- Use the adjustment panel to tweak endpoints or types if needed +- Click Apply to persist walls to the scene +- Review chat/journal log for traceability + +Notes +- Batching and multi-scene processing are not part of MVP; plan for future sprints if you want to scale. +- Security: only necessary scene data is sent; token remains with you. + +Next steps +- If you’d like, I can generate concrete starter patches (module.json + a minimal AIPrep.js skeleton and the SettingsPanel), plus the exact payload shapes ready to patch into your repo. I can also tailor naming and endpoint paths to your preferred conventions. diff --git a/src/AIEndpoint.js b/src/AIEndpoint.js new file mode 100644 index 0000000..9c513be --- /dev/null +++ b/src/AIEndpoint.js @@ -0,0 +1,16 @@ +// Lightweight HTTP client for the cloud AI endpoint +export async function aiPrepRequest(payload, endpoint, token) { + const resp = await fetch(endpoint, { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + 'Authorization': token ? `Bearer ${token}` : '' + }, + body: JSON.stringify(payload) + }); + if (!resp.ok) { + const err = await resp.text(); + throw new Error(`AI prep request failed: ${resp.status} ${resp.statusText} - ${err}`); + } + return resp.json(); +} diff --git a/src/AIPrep.js b/src/AIPrep.js new file mode 100644 index 0000000..1817969 --- /dev/null +++ b/src/AIPrep.js @@ -0,0 +1,25 @@ +// WallCraft AI: Minimal MVP skeleton for FoundryVTT module (WallCraft AI) +import { SettingsPanel } from './SettingsPanel.js'; +import { startAIPrepFlow } from './UIFlow.js'; + +export function initWallCraftAI() { + Hooks.on('ready', async function () { + if (!game.user?.isGM) return; + // Simple guidance dialog for first-time setup + new Dialog({ + title: 'WallCraft AI', + content: '

WallCraft AI is ready. Use Settings to configure the cloud endpoint, then start the MVP prep flow.

', + buttons: { + settings: { label: 'Settings', callback: () => SettingsPanel.open() }, + start: { label: 'Start MVP', callback: () => startAIPrepFlow() } + }, + default: 'start' + }).render(true); + }); +} + +Hooks.once('init', () => { + // Initialize basic settings with sane defaults if needed + // Actual settings are declared in SettingsPanel + initWallCraftAI(); +}); diff --git a/src/PreviewLayer.js b/src/PreviewLayer.js new file mode 100644 index 0000000..8f90c15 --- /dev/null +++ b/src/PreviewLayer.js @@ -0,0 +1,11 @@ +// Lightweight non-destructive preview layer for WallCraft AI +export class PreviewLayer { + static drawWalls(scene, walls) { + // Placeholder: In a full implementation this would render translucent wall overlays + console.log('[WallCraft AI] Preview walls:', walls); + } + + static clear() { + console.log('[WallCraft AI] Clearing previews'); + } +} diff --git a/src/SettingsPanel.js b/src/SettingsPanel.js new file mode 100644 index 0000000..7ecfd2c --- /dev/null +++ b/src/SettingsPanel.js @@ -0,0 +1,36 @@ +// Settings UI for WallCraft AI (endpoint, token, provider) +export class SettingsPanel { + static open() { + const html = ` +
+
+
+ +
+
+
+ +
+
+
+ +
+
`; + new Dialog({ + title: 'WallCraft AI Settings', + content: html, + buttons: { + save: { label: 'Save', callback: (dlg) => { + const endpoint = dlg.find('#wca-endpoint').val(); + const token = dlg.find('#wca-token').val(); + const provider = dlg.find('#wca-provider').val(); + // Persist via Foundry settings + game.settings.set('wallcraft-ai', 'endpointUrl', endpoint); + game.settings.set('wallcraft-ai', 'apiToken', token); + game.settings.set('wallcraft-ai', 'providerName', provider); + }} + }, + default: 'save' + }).render(true); + } +} diff --git a/src/UIFlow.js b/src/UIFlow.js new file mode 100644 index 0000000..c055cb9 --- /dev/null +++ b/src/UIFlow.js @@ -0,0 +1,10 @@ +// Basic UI flow helpers for WallCraft AI (MVP) +export function startAIPrepFlow() { + new Dialog({ + title: 'WallCraft AI Prep (MVP)', + content: '

Trigger cloud AI to generate wall layout for the current scene. This is a placeholder MVP flow.

', + buttons: { + ok: { label: 'OK' } + } + }).render(true); +} diff --git a/structure.md b/structure.md new file mode 100644 index 0000000..d8b2e05 --- /dev/null +++ b/structure.md @@ -0,0 +1,18 @@ +WallCraft AI – Default File Structure + +- /modules/wallcraft-ai/ + - module.json + - /src/ + - AIPrep.js + - AIEndpoint.js + - PreviewLayer.js + - SettingsPanel.js + - UIFlow.js + - /agents.md + - /data-contracts.md + - /api-contract.md + - /onboarding.md + - /glossary.md + - /quick-start.md + +This structure keeps the core module logic separated from the documentation and keeps the docs versioned with the module code.