@dcl-regenesislabs/opendcl 0.1.0-22234509684.commit-63dfd19

package/README.md

@@ -0,0 +1,234 @@
+# OpenDCL 🧪
+
+[![CI](https://github.com/dcl-regenesislabs/opendcl/actions/workflows/ci.yaml/badge.svg)](https://github.com/dcl-regenesislabs/opendcl/actions/workflows/ci.yaml)
+
+AI coding assistant for Decentraland SDK7 scene development.
+
+OpenDCL is a terminal-based AI agent that understands Decentraland's SDK, components, and patterns out of the box. It helps creators — from beginners to experienced developers — build interactive 3D scenes faster using natural language.
+
+## Features
+
+- **Branded header** — on startup, displays a block-character "Decentraland" ASCII art banner with version and working directory. Falls back to a compact text header on narrow terminals
+- **Multi-provider LLM support** — works with Claude, OpenAI, Google, Ollama (free/local), OpenRouter, and more
+- **Scene-aware** — automatically detects your project's `scene.json`, SDK version, and entry points
+- **18 built-in skills** — scaffolding, 3D models, interactivity, UI, animations, multiplayer, authoritative server, audio/video, deployment (Genesis City & Worlds), optimization, smart items, camera control, lighting, player/avatar, NFT/blockchain, advanced rendering, advanced input
+- **Integrated commands** — `/init` to scaffold, `/preview` to launch the dev server, `/tasks` to manage running processes, `/review` to audit code
+- **TypeScript validation** — catches type errors immediately after writing code
+- **Free 3D asset catalog** — 900+ CC0-licensed models the agent can suggest and help you use
+- **Session persistence** — pick up where you left off across sessions
+
+## Quick Start
+
+```bash
+# Install
+npm install -g @dcl-regenesislabs/opendcl
+
+# Run in any directory
+opendcl
+```
+
+On first run, type `/setup` to configure a cloud API provider (Anthropic, OpenAI, Google, etc.) or `/setup-ollama` to install [Ollama](https://ollama.com/) and use a free local model.
+
+### In an Empty Folder
+
+```
+$ opendcl
+> Create a medieval tavern scene with a bar, tables, and a fireplace
+```
+
+OpenDCL will scaffold `scene.json`, `package.json`, `tsconfig.json`, and `src/index.ts` with your scene.
+
+### In an Existing Scene
+
+```
+$ cd my-scene/
+$ opendcl
+> Add a click handler to the door that opens it with an animation
+```
+
+OpenDCL reads your scene context and modifies existing code without overwriting it.
+
+## Use with Any AI Agent
+
+Install just the skills into your preferred AI coding agent — no opendcl installation required:
+
+```bash
+# Install all Decentraland skills (Claude Code, Cursor, Codex, Windsurf, and 35+ more)
+npx skills add dcl-regenesislabs/opendcl
+
+# List available skills first
+npx skills add dcl-regenesislabs/opendcl --list
+
+# Install specific skills only
+npx skills add dcl-regenesislabs/opendcl --skill create-scene --skill multiplayer-sync
+
+# Install globally (available in all projects)
+npx skills add dcl-regenesislabs/opendcl -g
+```
+
+This uses the open [skills](https://github.com/vercel-labs/skills) CLI to copy SKILL.md files into your agent's skills directory.
+
+> **Note:** The full OpenDCL agent adds auto TypeScript validation, scene context detection, and slash commands (`/preview`, `/init`, `/deploy`) on top of these skills.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/setup` | Configure a cloud API provider (Anthropic, OpenAI, Google, etc.) |
+| `/setup-ollama` | Install Ollama and configure a free local LLM model |
+| `/init` | Scaffold a new Decentraland scene in the current directory |
+| `/preview` | Start the Bevy-web preview server and open the scene in browser |
+| `/deploy` | Deploy the scene to Genesis City or a World (auto-detects from scene.json) |
+| `/tasks` | Interactively manage running background processes (preview server, etc.) |
+| `/review` | Review scene code for quality, performance, and SDK7 best practices |
+| `/explain <concept>` | Explain a Decentraland SDK7 concept (e.g., `/explain tweens`) |
+
+## Skills
+
+OpenDCL loads domain-specific skills on demand based on what you're asking:
+
+| Skill | Triggered when you want to... |
+|-------|-------------------------------|
+| `create-scene` | Start a new project, scaffold files |
+| `add-3d-models` | Load .glb models, browse free asset catalog |
+| `add-interactivity` | Add click handlers, hover effects, triggers |
+| `build-ui` | Create HUDs, menus, buttons with React-ECS |
+| `animations-tweens` | Animate objects, play GLTF animations |
+| `multiplayer-sync` | Sync state between players |
+| `authoritative-server` | Server-authoritative multiplayer with anti-cheat, storage, env vars |
+| `audio-video` | Add sounds, music, video screens |
+| `deploy-scene` | Publish to Genesis City (LAND-based) |
+| `deploy-worlds` | Publish to a World (DCL NAME or ENS domain) |
+| `optimize-scene` | Fix performance, stay within limits |
+| `smart-items` | Use asset pack smart items |
+| `camera-control` | Switch camera modes, cinematic cameras, cutscenes |
+| `lighting-environment` | Add lights, shadows, day/night cycle, glow effects |
+| `player-avatar` | Player data, emotes, attachments, NPC avatars |
+| `nft-blockchain` | Display NFTs, wallet checks, smart contracts |
+| `advanced-rendering` | Billboards, 3D text, materials, transparency |
+| `advanced-input` | Cursor state, movement restriction, WASD patterns |
+
+## How It Works
+
+OpenDCL is built on [pi-coding-agent](https://github.com/badlogic/pi-mono), the agent engine behind [OpenClaw](https://github.com/openclaw/openclaw). It adds Decentraland-specific:
+
+- **System prompt** with SDK7 architecture knowledge (ECS, QuickJS sandbox, parcel constraints)
+- **Extensions** that detect your project, inject context, validate TypeScript, and provide slash commands
+- **Skills** with detailed guides for every common scene development task
+- **Reference docs** (87KB SDK reference, component tables, code examples, 3D asset catalog)
+
+The agent has full access to standard coding tools (read, write, edit, bash, grep, find) and uses them to understand and modify your scene code.
+
+## Project Structure
+
+```
+opendcl/
+├── src/
+│   ├── index.ts              # CLI entry point
+│   └── scene-context.ts      # Scene detection & context formatting
+├── extensions/
+│   ├── dcl-context.ts        # Auto-detect scene, inject metadata
+│   ├── dcl-init.ts           # /init command
+│   ├── dcl-preview.ts        # /preview command
+│   ├── dcl-deploy.ts         # /deploy command
+│   ├── dcl-setup.ts          # /setup command (cloud API provider config)
+│   ├── dcl-setup-ollama.ts   # /setup-ollama command (Ollama setup wizard)
+│   ├── dcl-status.ts         # Thinking/streaming status (elapsed time + tokens)
+│   ├── dcl-update-check.ts   # Checks npm for newer OpenDCL versions
+│   ├── dcl-validate.ts       # Post-write TypeScript validation
+│   ├── dcl-tasks.ts          # /tasks command (process manager)
+│   └── process-registry.ts   # Shared background process registry
+├── skills/                   # 18 SKILL.md files (domain expertise)
+├── prompts/                  # System prompt + command templates
+├── context/                  # SDK7 reference docs + asset catalog
+└── tests/                    # Vitest test suites
+```
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/dcl-regenesislabs/opendcl.git
+cd opendcl
+npm install
+
+# Build
+npm run build
+
+# Run locally
+node dist/index.js
+
+# Run tests
+npm test
+
+# Watch mode (rebuild on changes)
+npm run dev
+```
+
+### Testing
+
+Tests are organized into two tiers:
+
+- **Unit tests** (`tests/unit/`) — static analysis of file contents, frontmatter, and patterns
+- **Integration tests** (`tests/integration/`) — dynamic imports, mock registration, cross-extension wiring, and process lifecycle verification
+
+Integration tests catch wiring bugs (e.g., referencing a nonexistent extension file in `index.ts`) that static analysis alone would miss.
+
+### Adding a Skill
+
+Skills are markdown files — no code changes needed:
+
+1. Create `skills/my-skill/SKILL.md`
+2. Add frontmatter with `name` and `description`
+3. Write the instructions the agent should follow
+
+```markdown
+---
+name: my-skill
+description: Brief description of when this skill should be used
+---
+
+# My Skill
+
+Instructions for the agent...
+```
+
+The `description` field determines when the agent loads the skill. Make it specific about the user intent it covers.
+
+### Adding Context
+
+Drop a `.md` file in `context/` and reference it from your skills. The agent reads context files on demand to avoid bloating the context window.
+
+## LLM Providers
+
+OpenDCL supports any provider compatible with pi-coding-agent:
+
+| Provider | API Key Env Var | Notes |
+|----------|----------------|-------|
+| Anthropic (Claude) | `ANTHROPIC_API_KEY` | Best quality |
+| OpenAI | `OPENAI_API_KEY` | GPT-4o, o1, etc. |
+| Google | `GOOGLE_API_KEY` | Gemini models |
+| Ollama | — | Free, runs locally |
+| OpenRouter | `OPENROUTER_API_KEY` | Access to many models |
+
+Set the environment variable or enter the key on first run. Switch models anytime with `Ctrl+P`.
+
+## Requirements
+
+- Node.js >= 18
+- npm
+
+## Contributing
+
+Contributions are welcome! The easiest way to contribute is by adding or improving skills:
+
+1. Fork the repository
+2. Create a new skill in `skills/<name>/SKILL.md`
+3. Test that the skill loads: `npm test`
+4. Submit a pull request
+
+For bugs and feature requests, please [open an issue](https://github.com/dcl-regenesislabs/opendcl/issues).
+
+## License
+
+Apache-2.0

package/context/components-reference.md

@@ -0,0 +1,113 @@
+# Decentraland SDK7 Components Quick Reference
+
+All components are imported from `@dcl/sdk/ecs`.
+
+## Transform & Positioning
+
+| Component | Key Fields | Description |
+|-----------|-----------|-------------|
+| **Transform** | `position: Vector3`, `rotation: Quaternion`, `scale: Vector3`, `parent?: Entity` | Position, rotation, and scale of an entity. Parent for hierarchy. |
+
+## 3D Rendering
+
+| Component | Key Fields | Description |
+|-----------|-----------|-------------|
+| **MeshRenderer** | Static methods: `setBox()`, `setSphere()`, `setCylinder()`, `setPlane()` | Renders primitive 3D shapes. |
+| **MeshCollider** | Static methods: `setBox()`, `setSphere()`, `setCylinder()`, `setPlane()` | Adds collision geometry for physics/pointer events. |
+| **Material** | Static methods: `setPbrMaterial({ albedoColor, metallic, roughness, texture })`, `setBasicMaterial()` | PBR or unlit material for meshes. |
+| **GltfContainer** | `src: string`, `visibleMeshesCollisionMask?`, `invisibleMeshesCollisionMask?` | Loads a .glb/.gltf 3D model file. |
+| **GltfContainerLoadingState** | `currentState` | Read-only loading state for GLTF models. |
+| **GltfNodeModifiers** | `nodes: Array<{ path, visibleMeshes, invisibleMeshes }>` | Modify visibility of specific nodes in GLTF. |
+| **Billboard** | `billboardMode: BillboardMode` | Makes entity always face the camera. |
+| **VisibilityComponent** | `visible: boolean` | Show/hide entity without removing it. |
+| **NftShape** | `src: string (urn)`, `style?` | Display an NFT artwork frame. |
+| **TextShape** | `text: string`, `fontSize?: number`, `textColor?: Color4`, `font?: Font` | Render 3D text in the scene. |
+| **LightSource** | `type`, `color`, `intensity`, `range`, `innerAngle`, `outerAngle`, `shadows` | Add point, spot, or directional lights. |
+
+## Interaction & Input
+
+| Component | Key Fields | Description |
+|-----------|-----------|-------------|
+| **PointerEvents** | `pointerEvents: Array<{ eventType, eventInfo: { button, hoverText, maxDistance } }>` | Define clickable/hoverable areas. Use `pointerEventsSystem.onPointerDown()` helper. |
+| **PointerEventsResult** | Read-only | Results of pointer events (which button, hit point). |
+| **PointerLock** | `isPointerLocked: boolean` | Whether pointer is locked (first-person mode). |
+| **PrimaryPointerInfo** | Read-only | Position and entity of the primary pointer. |
+| **InputModifier** | `mode` | Modify input behavior for the entity. |
+| **Raycast** | `direction`, `maxDistance`, `queryType`, `continuous` | Cast rays for collision detection. |
+| **RaycastResult** | Read-only | Results of a raycast (hits, distances). |
+| **TriggerArea** | `area: { box }`, `layerMask` | Define trigger volumes that detect player entry. |
+| **TriggerAreaResult** | Read-only | Which entities are inside the trigger. |
+
+## Animation & Movement
+
+| Component | Key Fields | Description |
+|-----------|-----------|-------------|
+| **Animator** | `states: Array<{ clip, playing, loop, speed, weight }>` | Play animations embedded in GLTF models. |
+| **Tween** | `mode: { move, rotate, scale }`, `duration`, `easingFunction`, `currentTime` | Animate entity properties over time. |
+| **TweenSequence** | `sequence: Array<{ ... }>`, `loop` | Chain multiple tweens together. |
+| **TweenState** | Read-only | Current state of a tween. |
+
+## Audio & Video
+
+| Component | Key Fields | Description |
+|-----------|-----------|-------------|
+| **AudioSource** | `audioClipUrl: string`, `playing: boolean`, `loop: boolean`, `volume: number`, `pitch: number` | Play audio clips (.mp3, .ogg, .wav). |
+| **AudioStream** | `url: string`, `playing: boolean`, `volume: number` | Stream audio from a URL. |
+| **AudioEvent** | Read-only | Audio playback events. |
+| **VideoPlayer** | `src: string`, `playing: boolean`, `loop: boolean`, `volume: number`, `playbackRate: number` | Play video on a surface. Requires `Material` with video texture. |
+| **VideoEvent** | Read-only | Video playback events. |
+
+## Player & Avatar
+
+| Component | Key Fields | Description |
+|-----------|-----------|-------------|
+| **PlayerIdentityData** | `address: string`, `isGuest: boolean` | Player's wallet address and guest status. |
+| **AvatarShape** | `id: string`, `name: string`, `bodyShape`, `wearables`, `emotes` | Render an avatar (for NPCs). |
+| **AvatarBase** | `skinColor`, `eyeColor`, `hairColor`, `bodyShapeUrn` | Base avatar appearance. |
+| **AvatarAttach** | `avatarId: string`, `anchorPointId` | Attach an entity to a player's avatar. |
+| **AvatarModifierArea** | `area`, `modifiers: Array<AvatarModifierType>` | Modify avatars in an area (hide, freeze). |
+| **AvatarEmoteCommand** | `emoteUrn`, `loop` | Trigger avatar emotes. |
+| **AvatarEquippedData** | Read-only | Data about equipped wearables. |
+
+## Camera
+
+| Component | Key Fields | Description |
+|-----------|-----------|-------------|
+| **CameraMode** | `mode: CameraType` | Set camera to first-person or third-person. |
+| **CameraModeArea** | `area`, `mode` | Force camera mode in an area. |
+| **MainCamera** | Read-only | Access main camera position/rotation. |
+| **VirtualCamera** | `lookAtEntity?`, `defaultTransition` | Create cinematic camera angles. |
+
+## UI Components (React-ECS)
+
+Imported from `@dcl/sdk/react-ecs`:
+
+| Component | Key Fields | Description |
+|-----------|-----------|-------------|
+| **UiTransform** | `width`, `height`, `positionType`, `flexDirection`, `alignItems`, `justifyContent`, `margin`, `padding`, `position` | Layout and positioning (CSS flexbox-like). |
+| **UiText** | `value: string`, `fontSize`, `color`, `textAlign`, `font` | Render text in UI. |
+| **UiBackground** | `color?`, `textureMode?`, `texture?` | Background color or image for UI elements. |
+| **UiInput** | `placeholder`, `fontSize`, `color`, `onSubmit` | Text input field. |
+| **UiInputResult** | Read-only | Input field value. |
+| **UiDropdown** | `options: string[]`, `selectedIndex`, `onChange` | Dropdown selector. |
+| **UiDropdownResult** | Read-only | Selected dropdown value. |
+| **UiCanvasInformation** | Read-only | Screen dimensions and device pixel ratio. |
+
+## System & Runtime
+
+| Component | Key Fields | Description |
+|-----------|-----------|-------------|
+| **EngineInfo** | Read-only: `tickNumber`, `totalRuntime`, `frameNumber` | Engine timing information. |
+| **RealmInfo** | Read-only: `realmName`, `networkId`, `baseUrl` | Current realm/server info. |
+| **SkyboxTime** | `time` | Control the time of day (skybox). |
+| **AssetLoad** | `src`, `type` | Request loading of external assets. |
+| **AssetLoadLoadingState** | Read-only | Loading state of external assets. |
+
+## Math Types (from `@dcl/sdk/math`)
+
+| Type | Factory | Description |
+|------|---------|-------------|
+| **Vector3** | `Vector3.create(x, y, z)`, `.Zero()`, `.One()`, `.Up()`, `.Forward()` | 3D position/direction. |
+| **Quaternion** | `Quaternion.fromEulerDegrees(x, y, z)`, `.Identity()` | Rotation. |
+| **Color4** | `Color4.create(r, g, b, a)`, `.Red()`, `.Blue()`, `.Green()`, `.White()`, `.Black()` | RGBA color (0-1 range). |
+| **Color3** | `Color3.create(r, g, b)` | RGB color. |