@lagless/create 0.0.56 → 0.0.58

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lagless/create",
-  "version": "0.0.56",
+  "version": "0.0.58",
   "license": "CC-BY-NC-4.0",
   "repository": {
     "type": "git",

package/templates/pixi-react/docs/04-input-system.md

@@ -173,6 +173,15 @@ const hooks: RoomHooks = {
       reason,
     });
   },
+  // Inspect or reject client inputs before broadcast:
+  onInput: (ctx, player, input) => {
+    // input: { tick, playerSlot, seq, payload }
+    // Return false to reject (sends CancelInput to sender)
+  },
+  // Called when input is rejected (validation or onInput):
+  onInputDeclined: (ctx, player, tick, seq, reason) => {
+    // reason: 0=TooOld, 1=TooFarFuture, 2=InvalidSlot, 3=Rejected
+  },
 };
 ```
 
@@ -190,6 +199,51 @@ for (const rpc of rpcs) {
 
 The key difference: server events have `rpc.meta.playerSlot === SERVER_SLOT` (255).
 
+## String Data in RPCs
+
+RPCs use numeric fields (`uint8`, `float32`, etc.), but sometimes you need to send string data (e.g., username in `PlayerJoined`). Use `encodeStringToUint8` / `decodeStringFromUint8` from `@lagless/binary` with `uint8[N]` array fields.
+
+**Encoding:** BMP-only UTF-16, fixed 2 bytes per character. Supports Latin, Cyrillic, CJK, Arabic, Greek. Emoji (non-BMP) are replaced with `?`.
+
+### Schema
+
+```yaml
+inputs:
+  PlayerJoined:
+    slot: uint8
+    username: uint8[64]   # 64 bytes = 32 characters max
+```
+
+### Sending (server hook)
+
+```typescript
+import { encodeStringToUint8 } from '@lagless/binary';
+
+onPlayerJoin(ctx, player) {
+  const { buffer } = encodeStringToUint8(player.username, 64);
+  ctx.emitServerEvent(PlayerJoined, { slot: player.slot, username: buffer });
+}
+```
+
+### Reading (system)
+
+```typescript
+import { decodeStringFromUint8 } from '@lagless/binary';
+
+const rpcs = this._input.collectTickRPCs(tick, PlayerJoined);
+for (const rpc of rpcs) {
+  const username = decodeStringFromUint8(rpc.data.username as Uint8Array);
+  // username is a JS string, e.g. "Игрок_123"
+}
+```
+
+### Key Points
+
+- `maxBytes` must be even (2 bytes per character). `maxBytes / 2` = max characters.
+- `encodeStringToUint8` returns `{ buffer: Uint8Array, truncated: boolean }`.
+- Truncation never splits a character — always clean cut.
+- Buffer is zero-padded; `decodeStringFromUint8` stops at first null (`0x0000`) or end of buffer.
+
 ## Adding a New Input Type
 
 1. **Schema** — Add to `ecs.yaml`:

package/templates/pixi-react/docs/07-multiplayer.md

@@ -85,6 +85,7 @@ const server = new RelayGameServer({
     config: {
       maxPlayers: 4,
       reconnectTimeoutMs: 15_000,
+      inputRecordingEnabled: true, // enable replay export
     },
     hooks,
     inputRegistry: MyInputRegistry,
@@ -170,6 +171,20 @@ export const hooks: RoomHooks = {
     // Persist results to database, etc.
   },
 
+  // Inspect or reject client inputs before broadcast (sync, called per input)
+  onInput: (ctx, player, input) => {
+    // input: { tick, playerSlot, seq, payload (Uint8Array) }
+    // Decode payload: InputBinarySchema.unpackBatch(registry, input.payload.buffer)
+    // Return false to reject (sends CancelInput with Rejected reason)
+    // Return void/true to accept
+  },
+
+  // Called when input is rejected (by validation or onInput returning false)
+  onInputDeclined: (ctx, player, tick, seq, reason) => {
+    // reason: 0=TooOld, 1=TooFarFuture, 2=InvalidSlot, 3=Rejected
+    // Use for logging, rate-limit tracking, anti-cheat analytics
+  },
+
   // Room is being disposed
   onRoomDisposed: (ctx) => {
     console.log('Room disposed:', ctx.roomId);
@@ -186,6 +201,23 @@ ctx.emitServerEvent(InputClass, data);  // Send server-originated RPC
 ctx.getPlayers();                        // Get all player info
 ctx.endMatch(results);                   // End the match
 ctx.roomId;                              // Room identifier
+ctx.exportRecordedInputs();              // RPCHistory binary (requires inputRecordingEnabled)
+ctx.exportReplay();                      // Full replay binary (seed + maxPlayers + fps + RPCHistory)
+```
+
+### Replay Export
+
+Enable `inputRecordingEnabled: true` in server config. All broadcast inputs (client + server events) are stored. Export in `onMatchEnd`:
+
+```typescript
+onMatchEnd: async (ctx, results) => {
+  const replay = ctx.exportReplay();
+  if (replay) {
+    // replay is ArrayBuffer — save to DB, file, or cloud storage
+    // Load later via ReplayInputProvider.createFromReplay(replay, inputRegistry)
+    await saveReplay(ctx.matchId, replay);
+  }
+},
 ```
 
 ## Server Events via emitServerEvent

package/templates/pixi-react/docs/09-recipes.md

@@ -100,6 +100,39 @@ Tags have no fields — they only occupy a bitmask bit (zero memory per entity).
    }
    ```
 
+## Send String Data in RPCs (e.g. Username)
+
+RPCs only support numeric fields. To send strings, use `uint8[N]` array fields with `encodeStringToUint8` / `decodeStringFromUint8`.
+
+1. Edit `ecs.yaml`:
+   ```yaml
+   inputs:
+     PlayerJoined:
+       slot: uint8
+       username: uint8[64]   # 64 bytes = 32 characters max
+   ```
+2. Run `pnpm codegen`
+3. Encode on send (server hook):
+   ```typescript
+   import { encodeStringToUint8 } from '@lagless/binary';
+
+   onPlayerJoin(ctx, player) {
+     const { buffer } = encodeStringToUint8(player.username, 64);
+     ctx.emitServerEvent(PlayerJoined, { slot: player.slot, username: buffer });
+   }
+   ```
+4. Decode in system:
+   ```typescript
+   import { decodeStringFromUint8 } from '@lagless/binary';
+
+   const rpcs = this._input.collectTickRPCs(tick, PlayerJoined);
+   for (const rpc of rpcs) {
+     const username = decodeStringFromUint8(rpc.data.username as Uint8Array);
+   }
+   ```
+
+**Supports:** Latin, Cyrillic, CJK, Arabic, Greek. **No emoji** — replaced with `?`.
+
 ## Add a New Entity Type
 
 1. Define components and filter in `ecs.yaml`:

package/templates/pixi-react/docs/api-quick-reference.md

@@ -82,6 +82,22 @@ for (const rpc of rpcs) {
 const buffer = inputProvider.getFrameRPCBuffer(tick);
 ```
 
+## String Encoding (for RPCs)
+
+```typescript
+import { encodeStringToUint8, decodeStringFromUint8 } from '@lagless/binary';
+
+// Encode string into fixed-size buffer (BMP UTF-16, 2 bytes/char)
+const { buffer, truncated } = encodeStringToUint8('Игрок', 64); // 32 chars max
+
+// Decode buffer back to string
+const str = decodeStringFromUint8(buffer); // 'Игрок'
+
+// Use with uint8[N] RPC fields:
+addRPC(PlayerJoined, { slot: 0, username: buffer });
+const name = decodeStringFromUint8(rpc.data.username as Uint8Array);
+```
+
 ## Signals
 
 ```typescript