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

package/skills/authoritative-server/SKILL.md

@@ -0,0 +1,329 @@
+---
+name: authoritative-server
+description: Build multiplayer scenes with a headless authoritative server that controls game state, validates changes, and prevents cheating. Install @dcl/sdk@auth-server and run with hammurabi-server. Use isServer() to branch logic, registerMessages() for client-server communication, validateBeforeChange() for server-only components, Storage for persistence, and EnvVar for configuration. Use when user wants authoritative server, anti-cheat, server-side validation, persistent storage, environment variables, or server messages.
+---
+
+# Authoritative Server Pattern
+
+Build multiplayer Decentraland scenes where a **headless server** controls game state, validates changes, and prevents cheating. The same codebase runs on both server and client, with the server having full authority.
+
+Before reading this skill, read `{baseDir}/../../context/sdk7-complete-reference.md` for general SDK7 knowledge. For basic CRDT multiplayer (no server), see the `multiplayer-sync` skill instead.
+
+## Setup
+
+Install the auth-server SDK branch:
+
+```bash
+npm install @dcl/sdk@auth-server
+```
+
+Your `scene.json` must include a world name:
+
+```json
+{
+  "worldConfiguration": {
+    "name": "my-world-name"
+  }
+}
+```
+
+Run the scene:
+
+```bash
+# With authoritative server (required for this pattern)
+npx @dcl/hammurabi-server@next
+
+# Standard dev server (no auth server, for client-only testing)
+npm run start
+```
+
+## Server/Client Branching
+
+Use `isServer()` to branch logic in a single codebase:
+
+```typescript
+import { isServer } from '@dcl/sdk/network'
+
+export async function main() {
+  if (isServer()) {
+    // Server-only: game logic, validation, state management
+    const { server } = await import('./server/server')
+    server()
+    return
+  }
+
+  // Client-only: UI, input, message sending
+  setupClient()
+  setupUi()
+}
+```
+
+The server runs your scene code headlessly (no rendering). It has access to all player positions via `PlayerIdentityData` and manages all authoritative game state.
+
+## Synced Components with Validation
+
+Define custom components that sync from server to all clients. **Always** use `validateBeforeChange()` to prevent clients from modifying server-authoritative state.
+
+### Custom Components (Global Validation)
+
+```typescript
+import { engine, Schemas } from '@dcl/sdk/ecs'
+import { AUTH_SERVER_PEER_ID } from '@dcl/sdk/network/message-bus-sync'
+
+export const GameState = engine.defineComponent('game:State', {
+  phase: Schemas.String,
+  score: Schemas.Number,
+  timeRemaining: Schemas.Number
+})
+
+// Restrict ALL modifications to server only
+GameState.validateBeforeChange((value) => {
+  return value.senderAddress === AUTH_SERVER_PEER_ID
+})
+```
+
+### Built-in Components (Per-Entity Validation)
+
+For built-in components like `Transform` and `GltfContainer`, use per-entity validation so you don't block client-side transforms on the player's own entities:
+
+```typescript
+import { Entity, Transform, GltfContainer } from '@dcl/sdk/ecs'
+import { AUTH_SERVER_PEER_ID } from '@dcl/sdk/network/message-bus-sync'
+
+type ComponentWithValidation = {
+  validateBeforeChange: (entity: Entity, cb: (value: { senderAddress: string }) => boolean) => void
+}
+
+function protectServerEntity(entity: Entity, components: ComponentWithValidation[]) {
+  for (const component of components) {
+    component.validateBeforeChange(entity, (value) => {
+      return value.senderAddress === AUTH_SERVER_PEER_ID
+    })
+  }
+}
+
+// Usage: after creating a server-managed entity
+const entity = engine.addEntity()
+Transform.create(entity, { position: Vector3.create(10, 5, 10) })
+GltfContainer.create(entity, { src: 'assets/model.glb' })
+protectServerEntity(entity, [Transform, GltfContainer])
+```
+
+### Syncing Entities
+
+After creating and protecting an entity, sync it to all clients:
+
+```typescript
+import { syncEntity } from '@dcl/sdk/network'
+
+syncEntity(entity, [Transform.componentId, GameState.componentId])
+```
+
+## Messages
+
+Use `registerMessages()` for client-to-server and server-to-client communication:
+
+### Define Messages
+
+```typescript
+import { Schemas } from '@dcl/sdk/ecs'
+import { registerMessages } from '@dcl/sdk/network'
+
+export const Messages = {
+  // Client -> Server
+  playerJoin: Schemas.Map({ displayName: Schemas.String }),
+  playerAction: Schemas.Map({ actionType: Schemas.String, data: Schemas.Number }),
+
+  // Server -> Client
+  gameEvent: Schemas.Map({ eventType: Schemas.String, playerName: Schemas.String })
+}
+
+export const room = registerMessages(Messages)
+```
+
+### Send Messages
+
+```typescript
+// Client sends to server
+room.send('playerJoin', { displayName: 'Alice' })
+
+// Server sends to ALL clients
+room.send('gameEvent', { eventType: 'ROUND_START', playerName: '' })
+
+// Server sends to ONE client
+room.send('gameEvent', { eventType: 'YOU_WIN', playerName: 'Alice' }, { to: [playerAddress] })
+```
+
+### Receive Messages
+
+```typescript
+// Server receives from client
+room.onMessage('playerJoin', (data, context) => {
+  if (!context) return
+  const playerAddress = context.from  // Wallet address of sender
+  console.log(`[Server] Player joined: ${data.displayName} (${playerAddress})`)
+})
+
+// Client receives from server
+room.onMessage('gameEvent', (data) => {
+  console.log(`Event: ${data.eventType}`)
+})
+```
+
+### Wait for Room Connection
+
+Before sending messages from the client, wait for the connected scene room:
+
+```typescript
+import { engine } from '@dcl/sdk/ecs'
+import { RealmInfo } from '@dcl/sdk/ecs'
+
+let joined = false
+engine.addSystem(() => {
+  if (joined) return
+  const realm = RealmInfo.getOrNull(engine.RootEntity)
+  if (realm?.isConnectedSceneRoom) {
+    joined = true
+    room.send('playerJoin', { displayName: 'Player' })
+  }
+})
+```
+
+## Server Reading Player Positions
+
+The server can read **actual** player positions — critical for anti-cheat:
+
+```typescript
+import { engine, PlayerIdentityData, Transform } from '@dcl/sdk/ecs'
+
+engine.addSystem(() => {
+  for (const [entity, identity] of engine.getEntitiesWith(PlayerIdentityData)) {
+    const transform = Transform.getOrNull(entity)
+    if (!transform) continue
+
+    const address = identity.address
+    const position = transform.position
+    // Use actual server-verified position, not client-reported data
+  }
+})
+```
+
+Never trust client-reported positions. Always read `PlayerIdentityData` + `Transform` on the server.
+
+## Storage
+
+Persist data across server restarts. **Server-only** — guard with `isServer()`.
+
+```typescript
+import { Storage } from '@dcl/sdk/server'
+```
+
+### World Storage (Global)
+
+Shared across all players:
+
+```typescript
+// Store
+await Storage.world.set('leaderboard', JSON.stringify(leaderboardData))
+
+// Retrieve
+const data = await Storage.world.get<string>('leaderboard')
+if (data) {
+  const leaderboard = JSON.parse(data)
+}
+
+// Delete
+await Storage.world.delete('oldKey')
+```
+
+### Player Storage (Per-Player)
+
+Keyed by player wallet address:
+
+```typescript
+// Store
+await Storage.player.set(playerAddress, 'highScore', String(score))
+
+// Retrieve
+const saved = await Storage.player.get<string>(playerAddress, 'highScore')
+const highScore = saved ? parseInt(saved) : 0
+
+// Delete
+await Storage.player.delete(playerAddress, 'highScore')
+```
+
+Storage only accepts strings. Use `JSON.stringify()`/`JSON.parse()` for objects and `String()`/`parseInt()` for numbers.
+
+Local development storage is at `node_modules/@dcl/sdk-commands/.runtime-data/server-storage.json`.
+
+## Environment Variables
+
+Configure your scene without hardcoding values. **Server-only** — guard with `isServer()`.
+
+```typescript
+import { EnvVar } from '@dcl/sdk/server'
+
+// Read a variable with default
+const maxPlayers = parseInt((await EnvVar.get('MAX_PLAYERS')) || '4')
+const debugMode = ((await EnvVar.get('DEBUG')) || 'false') === 'true'
+```
+
+### Local Development
+
+Create a `.env` file in your project root:
+
+```
+MAX_PLAYERS=8
+GAME_DURATION=300
+DEBUG=true
+```
+
+Add `.env` to your `.gitignore`.
+
+### Deploy to Production
+
+```bash
+# Set a variable
+npx sdk-commands deploy-env MAX_PLAYERS --value 8
+
+# Delete a variable
+npx sdk-commands deploy-env OLD_VAR --delete
+```
+
+Deployed env vars take precedence over `.env` file values.
+
+## Recommended Project Structure
+
+```
+src/
+├── index.ts              # Entry point — isServer() branching
+├── client/
+│   ├── setup.ts          # Client initialization, message handlers
+│   └── ui.tsx            # React ECS UI reading synced state
+├── server/
+│   ├── server.ts         # Server init, systems, message handlers
+│   └── gameState.ts      # Server state management class
+└── shared/
+    ├── schemas.ts        # Synced component definitions + validateBeforeChange
+    └── messages.ts       # Message definitions via registerMessages()
+```
+
+Put synced components and messages in `shared/` so both server and client import the same definitions. Keep server logic (Storage, EnvVar, game systems) in `server/`. Keep UI and client input in `client/`.
+
+## Testing & Debugging
+
+- **Log prefixes**: Use `[Server]` and `[Client]` prefixes in `console.log()` to distinguish server and client output in the terminal.
+- **Stale CRDT files**: If you see "Outside of the bounds of written data" errors, delete `main.crdt` and `main1.crdt` files and restart.
+- **Storage inspection**: Check `node_modules/@dcl/sdk-commands/.runtime-data/server-storage.json` to inspect persisted data during local development.
+- **No setTimeout/setInterval**: The DCL runtime does not support these. Use `engine.addSystem()` with a timer variable instead.
+- **Entity sync issues**: Verify you call `syncEntity(entity, [componentIds])` with the correct component IDs (`MyComponent.componentId`).
+
+## Important Notes
+
+- **Use `Schemas.Int64` for timestamps**: `Schemas.Number` corrupts large numbers (13+ digits). Always use `Schemas.Int64` for values like `Date.now()`.
+- **Room readiness**: Clients must wait for `RealmInfo.get(engine.RootEntity).isConnectedSceneRoom` before sending messages.
+- **Custom vs built-in validation**: Custom components use global `validateBeforeChange((value) => ...)`. Built-in components (Transform, GltfContainer) use per-entity `validateBeforeChange(entity, (value) => ...)`.
+- **Single codebase**: Both server and client run the same `index.ts` entry point. Use `isServer()` to branch.
+- **No Node.js APIs**: The DCL runtime uses sandboxed QuickJS — no `fs`, `http`, `setTimeout`, etc. Use SDK-provided APIs (Storage, EnvVar, engine systems) instead.
+- **SDK branch**: The auth-server pattern requires `@dcl/sdk@auth-server`, not the standard `@dcl/sdk` package.
+- For basic CRDT multiplayer without a server, see the `multiplayer-sync` skill.

package/skills/build-ui/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: build-ui
+description: Build 2D user interfaces for Decentraland scenes using React-ECS. Create HUDs, menus, health bars, scoreboards, dialogs, buttons, and input forms. Use when user wants to add UI, HUD, buttons, text overlays, menus, or on-screen elements.
+---
+
+# Building UI with React-ECS
+
+Decentraland SDK7 uses a React-like JSX system for 2D UI overlays.
+
+## Setup
+
+### File: src/ui.tsx
+```tsx
+import ReactEcs, { UiEntity, Label, Button } from '@dcl/sdk/react-ecs'
+
+function MyUI() {
+  return (
+    <UiEntity
+      uiTransform={{
+        width: '100%',
+        height: '100%',
+        justifyContent: 'center',
+        alignItems: 'center'
+      }}
+    >
+      <Label value="Hello Decentraland!" fontSize={24} />
+    </UiEntity>
+  )
+}
+
+export function setupUi() {
+  ReactEcs.setUiRenderer(MyUI)
+}
+```
+
+### File: src/index.ts
+```typescript
+import { setupUi } from './ui'
+
+export function main() {
+  setupUi()
+}
+```
+
+### Required tsconfig.json settings
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "@dcl/sdk/react-ecs-lib"
+  }
+}
+```
+
+## Core Components
+
+### UiEntity (Container)
+```tsx
+<UiEntity
+  uiTransform={{
+    width: 300,              // Pixels or '50%'
+    height: 200,
+    positionType: 'absolute', // 'absolute' or 'relative' (default)
+    position: { top: 10, right: 10 }, // Only with absolute
+    flexDirection: 'column',  // 'row' | 'column'
+    justifyContent: 'center', // 'flex-start' | 'center' | 'flex-end' | 'space-between'
+    alignItems: 'center',     // 'flex-start' | 'center' | 'flex-end' | 'stretch'
+    padding: { top: 10, bottom: 10, left: 10, right: 10 },
+    margin: { top: 5 },
+    display: 'flex'           // 'flex' | 'none' (hide)
+  }}
+  uiBackground={{
+    color: { r: 0, g: 0, b: 0, a: 0.8 } // Semi-transparent black
+  }}
+/>
+```
+
+### Label (Text)
+```tsx
+<Label
+  value="Score: 100"
+  fontSize={18}
+  color={{ r: 1, g: 1, b: 1, a: 1 }}
+  textAlign="middle-center"
+  font="sans-serif"
+  uiTransform={{ width: 200, height: 30 }}
+/>
+```
+
+### Button
+```tsx
+<Button
+  value="Click Me"
+  variant="primary"  // 'primary' | 'secondary'
+  fontSize={16}
+  uiTransform={{ width: 150, height: 40 }}
+  onMouseDown={() => {
+    console.log('Button clicked!')
+  }}
+/>
+```
+
+### Input
+```tsx
+import { Input } from '@dcl/sdk/react-ecs'
+
+<Input
+  placeholder="Type here..."
+  fontSize={14}
+  color={{ r: 1, g: 1, b: 1, a: 1 }}
+  uiTransform={{ width: 250, height: 35 }}
+  onSubmit={(value) => {
+    console.log('Submitted:', value)
+  }}
+/>
+```
+
+### Dropdown
+```tsx
+import { Dropdown } from '@dcl/sdk/react-ecs'
+
+<Dropdown
+  options={['Option A', 'Option B', 'Option C']}
+  selectedIndex={0}
+  onChange={(index) => {
+    console.log('Selected:', index)
+  }}
+  uiTransform={{ width: 200, height: 35 }}
+  fontSize={14}
+/>
+```
+
+## State Management
+
+Use module-level variables for UI state (React hooks are NOT available):
+
+```tsx
+let score = 0
+let showMenu = false
+
+function GameUI() {
+  return (
+    <UiEntity uiTransform={{ width: '100%', height: '100%' }}>
+      {/* HUD - always visible */}
+      <Label
+        value={`Score: ${score}`}
+        fontSize={20}
+        uiTransform={{
+          positionType: 'absolute',
+          position: { top: 10, left: 10 }
+        }}
+      />
+
+      {/* Menu - conditionally shown */}
+      {showMenu && (
+        <UiEntity
+          uiTransform={{
+            width: 300,
+            height: 400,
+            positionType: 'absolute',
+            position: { top: '50%', left: '50%' }
+          }}
+          uiBackground={{ color: { r: 0.1, g: 0.1, b: 0.1, a: 0.9 } }}
+        >
+          <Label value="Game Menu" fontSize={24} />
+          <Button
+            value="Resume"
+            variant="primary"
+            onMouseDown={() => { showMenu = false }}
+            uiTransform={{ width: 200, height: 40 }}
+          />
+        </UiEntity>
+      )}
+    </UiEntity>
+  )
+}
+
+// Update state from game logic
+export function addScore(points: number) {
+  score += points
+}
+
+export function toggleMenu() {
+  showMenu = !showMenu
+}
+```
+
+## Common UI Patterns
+
+### Health Bar
+```tsx
+let health = 100
+
+function HealthBar() {
+  return (
+    <UiEntity
+      uiTransform={{
+        width: 200, height: 20,
+        positionType: 'absolute',
+        position: { bottom: 20, left: '50%' }
+      }}
+      uiBackground={{ color: { r: 0.3, g: 0.3, b: 0.3, a: 0.8 } }}
+    >
+      <UiEntity
+        uiTransform={{ width: `${health}%`, height: '100%' }}
+        uiBackground={{ color: { r: 0.2, g: 0.8, b: 0.2, a: 1 } }}
+      />
+    </UiEntity>
+  )
+}
+```
+
+### Image Background
+```tsx
+<UiEntity
+  uiTransform={{ width: 200, height: 200 }}
+  uiBackground={{
+    textureMode: 'stretch',
+    texture: { src: 'images/logo.png' }
+  }}
+/>
+```
+
+## Important Notes
+
+- React hooks (`useState`, `useEffect`, etc.) are **NOT** available — use module-level variables
+- The UI renderer re-renders every frame, so state changes are reflected immediately
+- UI is rendered as a 2D overlay on top of the 3D scene
+- Use `display: 'none'` in `uiTransform` to hide elements without removing them
+- File extension must be `.tsx` for JSX support
+- Only one `ReactEcs.setUiRenderer()` call per scene — combine all UI into one root component