@auraindustry/aurajs 0.0.7 → 0.1.0

package/templates/create/local-multiplayer/prefabs/player.prefab.js

@@ -0,0 +1,99 @@
+import { clamp } from '../src/starter-utils/index.js';
+import { LOCAL_MULTIPLAYER_CONFIG } from '../config/gameplay/local-multiplayer.config.js';
+import { findSpawnSlot } from '../content/gameplay/room-layout.js';
+
+export const LOCAL_PLAYER_SIZE = Object.freeze({
+  width: LOCAL_MULTIPLAYER_CONFIG.playerWidth,
+  height: LOCAL_MULTIPLAYER_CONFIG.playerHeight,
+});
+
+export const LOCAL_PLAYER_SPEED = LOCAL_MULTIPLAYER_CONFIG.playerSpeed;
+
+export const LOCAL_PLAYER_COLORS = Object.freeze([
+  { r: 0.28, g: 0.78, b: 0.98 },
+  { r: 0.98, g: 0.56, b: 0.34 },
+]);
+
+const localMultiplayerPlayerPrefab = {
+  id: 'player',
+  kind: 'prefab',
+  role: 'player',
+  view: {
+    kind: 'actor2d',
+    collider: {
+      shape: 'rect',
+      size: {
+        x: LOCAL_PLAYER_SIZE.width,
+        y: LOCAL_PLAYER_SIZE.height,
+      },
+    },
+  },
+  components: {
+    movementProfile: 'arcade',
+    multiplayerRole: 'local-room-avatar',
+  },
+  hooks: {},
+  notes: [
+    'Keep starter-owned local-room avatar tuning here before promoting it into a broader multiplayer runtime seam.',
+    'This prefab stays agnostic about transport; the starter defaults to local-first hosting and can promote the same room-code flow through aura.config.json -> multiplayer.',
+  ],
+};
+
+function defaultPlayerLabel(id) {
+  return id === 0 ? 'host' : `p${id}`;
+}
+
+export function createPlayerPrefab() {
+  return localMultiplayerPlayerPrefab;
+}
+
+export function createLocalPlayerState(id = 0, label = defaultPlayerLabel(id)) {
+  const spawnSlot = findSpawnSlot(id === 0 ? 'host' : 'guest');
+  return {
+    x: spawnSlot?.x ?? (id === 0 ? 180 : LOCAL_MULTIPLAYER_CONFIG.width - 216),
+    y: spawnSlot?.y ?? (id === 0 ? 210 : 300),
+    label,
+    color: LOCAL_PLAYER_COLORS[id % LOCAL_PLAYER_COLORS.length],
+    hidden: false,
+  };
+}
+
+export function applyLocalPlayerMovement(playerState, input, dt) {
+  const dx = Number(input && input.dx) || 0;
+  const dy = Number(input && input.dy) || 0;
+  return {
+    ...playerState,
+    x: clamp(
+      playerState.x + (dx * LOCAL_PLAYER_SPEED * dt),
+      24,
+      LOCAL_MULTIPLAYER_CONFIG.width - LOCAL_PLAYER_SIZE.width - 24,
+    ),
+    y: clamp(
+      playerState.y + (dy * LOCAL_PLAYER_SPEED * dt),
+      96,
+      LOCAL_MULTIPLAYER_CONFIG.height - LOCAL_PLAYER_SIZE.height - 28,
+    ),
+    hidden: false,
+  };
+}
+
+export function drawLocalPlayerState(playerState, key = 'player') {
+  if (!playerState || playerState.hidden) return;
+  const color = playerState.color || LOCAL_PLAYER_COLORS[0];
+  aura.draw2d.rectFill(
+    playerState.x,
+    playerState.y,
+    LOCAL_PLAYER_SIZE.width,
+    LOCAL_PLAYER_SIZE.height,
+    aura.rgb(color.r, color.g, color.b),
+  );
+  aura.draw2d.text(
+    playerState.label || key,
+    playerState.x - 2,
+    playerState.y - 14,
+    11,
+    aura.rgb(0.92, 0.94, 0.98),
+  );
+}
+
+export default localMultiplayerPlayerPrefab;

package/templates/create/local-multiplayer/scenes/boot.scene.js

@@ -0,0 +1,12 @@
+export function createBootScene() {
+  return {
+    id: 'boot',
+    nextSceneId: 'gameplay',
+    notes: [
+      'Keep long-lived boot orchestration here if the starter grows beyond the current local-first room-code loop.',
+      'Do not move room/session ownership into src/main.js; keep it in the authored runtime and scene files.',
+    ],
+  };
+}
+
+export default createBootScene;

package/templates/create/local-multiplayer/scenes/gameplay.scene.js

@@ -0,0 +1,443 @@
+import { axisFromKeys } from '../src/starter-utils/index.js';
+import { ensureSessionState, ensureUiState } from '../src/runtime/app-state.js';
+import { LOCAL_MULTIPLAYER_CONFIG } from '../config/gameplay/local-multiplayer.config.js';
+import {
+  applyLocalPlayerMovement,
+  createLocalPlayerState,
+  drawLocalPlayerState,
+} from '../prefabs/player.prefab.js';
+import { ROOM_LAYOUT } from '../content/gameplay/room-layout.js';
+
+function hasMethod(obj, method) {
+  return Boolean(obj) && typeof obj[method] === 'function';
+}
+
+function failWithReason(reasonCode, message) {
+  throw new Error(`[local-multiplayer-template] ${message} [reason:${reasonCode}]`);
+}
+
+function normalizeConnectivityMode(value) {
+  const normalized = String(value || '').trim().toLowerCase();
+  if (normalized === 'auto' || normalized === 'internet' || normalized === 'internet-auto' || normalized === 'online') {
+    return 'auto';
+  }
+  if (normalized === 'relay' || normalized === 'internet-relay') {
+    return 'relay';
+  }
+  return 'local';
+}
+
+function readOptionalText(value) {
+  const normalized = typeof value === 'string' ? value.trim() : '';
+  return normalized || null;
+}
+
+function readAuraEnv(name) {
+  if (typeof aura === 'undefined' || typeof aura.env !== 'function') {
+    return null;
+  }
+  return readOptionalText(aura.env(name));
+}
+
+function readAuraEnvBoolean(name) {
+  const raw = readAuraEnv(name);
+  if (!raw) return null;
+  const normalized = raw.toLowerCase();
+  if (normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on') {
+    return true;
+  }
+  if (normalized === '0' || normalized === 'false' || normalized === 'no' || normalized === 'off') {
+    return false;
+  }
+  return null;
+}
+
+function isKnownConnectivityMode(value) {
+  const normalized = String(value || '').trim().toLowerCase();
+  return normalized === 'local'
+    || normalized === 'auto'
+    || normalized === 'internet'
+    || normalized === 'internet-auto'
+    || normalized === 'online'
+    || normalized === 'relay'
+    || normalized === 'internet-relay';
+}
+
+function resolveRoomConfig() {
+  return {
+    roomCode: (readAuraEnv('AURA_MULTIPLAYER_ROOM_CODE') || ROOM_LAYOUT.roomCode).toUpperCase(),
+    roomName: readAuraEnv('AURA_MULTIPLAYER_ROOM_NAME') || ROOM_LAYOUT.roomName,
+  };
+}
+
+function resolveConnectivityConfig() {
+  const raw = LOCAL_MULTIPLAYER_CONFIG.connectivity;
+  const envMode = readAuraEnv('AURA_MULTIPLAYER_CONNECTIVITY_MODE');
+  const envRelayHost = readAuraEnv('AURA_MULTIPLAYER_RELAY_HOST') || readAuraEnv('AURA_MULTIPLAYER_RELAY');
+  const envCoordinatorUrl = readAuraEnv('AURA_COORDINATOR_URL');
+  const envRelayUrl = readAuraEnv('AURA_RELAY_URL');
+
+  if (typeof raw === 'string') {
+    const value = readOptionalText(raw);
+    if (!value) {
+      return {
+        mode: envRelayHost || envCoordinatorUrl || envRelayUrl ? 'auto' : 'local',
+        relayHost: envRelayHost,
+        coordinatorUrl: envCoordinatorUrl,
+        relayUrl: envRelayUrl,
+      };
+    }
+    if (isKnownConnectivityMode(value)) {
+      const mode = normalizeConnectivityMode(value);
+      return {
+        mode: (envRelayHost || envCoordinatorUrl || envRelayUrl) && mode !== 'relay' ? 'auto' : mode,
+        relayHost: envRelayHost,
+        coordinatorUrl: envCoordinatorUrl,
+        relayUrl: envRelayUrl,
+      };
+    }
+    return {
+      mode: 'auto',
+      relayHost: value,
+      coordinatorUrl: envCoordinatorUrl,
+      relayUrl: envRelayUrl,
+    };
+  }
+
+  if (!raw || typeof raw !== 'object') {
+    return {
+      mode: envRelayHost || envCoordinatorUrl || envRelayUrl ? 'auto' : 'local',
+      relayHost: envRelayHost,
+      coordinatorUrl: envCoordinatorUrl,
+      relayUrl: envRelayUrl,
+    };
+  }
+  const relayHost = readOptionalText(raw.relay || raw.relayHost) || envRelayHost;
+  const coordinatorUrl = readOptionalText(raw.coordinatorUrl) || envCoordinatorUrl;
+  const relayUrl = readOptionalText(raw.relayUrl) || envRelayUrl;
+  const requestedMode = normalizeConnectivityMode(envMode || raw.mode || raw.internetMode || raw.hostingMode);
+  const mode = relayHost || coordinatorUrl || relayUrl
+    ? (requestedMode === 'relay' ? 'relay' : 'auto')
+    : requestedMode;
+  return {
+    mode,
+    relayHost,
+    coordinatorUrl,
+    relayUrl,
+  };
+}
+
+function resolveDiagnosticsConfig() {
+  const enabled = readAuraEnvBoolean('AURA_MULTIPLAYER_SHOW_DIAGNOSTICS');
+  return {
+    enabled: enabled !== false,
+  };
+}
+
+const ROOM_CONFIG = resolveRoomConfig();
+const CONNECTIVITY_CONFIG = resolveConnectivityConfig();
+const DIAGNOSTICS_CONFIG = resolveDiagnosticsConfig();
+const LAUNCH_JOIN_CODE = (() => {
+  const value = readAuraEnv('AURA_MULTIPLAYER_JOIN_CODE');
+  return value ? value.toUpperCase() : null;
+})();
+
+function usesInternetBackedHosting() {
+  return CONNECTIVITY_CONFIG.mode !== 'local';
+}
+
+function launchedViaExplicitJoin() {
+  return Boolean(LAUNCH_JOIN_CODE);
+}
+
+function resolveHostFallbackSeconds() {
+  const configured = Math.max(0, Number(LOCAL_MULTIPLAYER_CONFIG.hostFallbackSeconds) || 0);
+  if (!usesInternetBackedHosting()) {
+    return configured;
+  }
+  return Math.max(configured, 2.5);
+}
+
+function assertLocalMultiplayerCapabilities() {
+  const missing = [];
+  if (!hasMethod(aura.input, 'isKeyDown')) missing.push('aura.input.isKeyDown');
+  if (!hasMethod(aura.draw2d, 'clear')) missing.push('aura.draw2d.clear');
+  if (!hasMethod(aura.draw2d, 'rectFill')) missing.push('aura.draw2d.rectFill');
+  if (!hasMethod(aura.draw2d, 'text')) missing.push('aura.draw2d.text');
+  if (typeof aura.rgb !== 'function') missing.push('aura.rgb');
+  if (!hasMethod(aura.multiplayer, 'configure')) missing.push('aura.multiplayer.configure');
+  if (!hasMethod(aura.multiplayer, 'getAllPlayerInputs')) missing.push('aura.multiplayer.getAllPlayerInputs');
+  if (!hasMethod(aura.multiplayer, 'getAllState')) missing.push('aura.multiplayer.getAllState');
+  if (!hasMethod(aura.multiplayer, 'getPlayerCount')) missing.push('aura.multiplayer.getPlayerCount');
+  if (!hasMethod(aura.multiplayer, 'getRoomInfo')) missing.push('aura.multiplayer.getRoomInfo');
+  if (!hasMethod(aura.multiplayer, 'getState')) missing.push('aura.multiplayer.getState');
+  if (!hasMethod(aura.multiplayer, 'host')) missing.push('aura.multiplayer.host');
+  if (!hasMethod(aura.multiplayer, 'isConnected')) missing.push('aura.multiplayer.isConnected');
+  if (!hasMethod(aura.multiplayer, 'onPlayerJoin')) missing.push('aura.multiplayer.onPlayerJoin');
+  if (!hasMethod(aura.multiplayer, 'onPlayerLeave')) missing.push('aura.multiplayer.onPlayerLeave');
+  if (!hasMethod(aura.multiplayer, 'sendInput')) missing.push('aura.multiplayer.sendInput');
+  if (!hasMethod(aura.multiplayer, 'setState')) missing.push('aura.multiplayer.setState');
+
+  if (missing.length > 0) {
+    failWithReason('missing_runtime_api', `runtime missing required APIs: ${missing.join(', ')}`);
+  }
+}
+
+function createSessionSeed() {
+  return {
+    runsStarted: 0,
+    lastRole: 'pending',
+    lastRoomCode: ROOM_CONFIG.roomCode,
+    lastRoomName: ROOM_CONFIG.roomName,
+    lastPlayerCount: 0,
+    lastConnected: false,
+    lastSceneId: 'gameplay',
+  };
+}
+
+function createUiSeed() {
+  return {
+    showControlsHint: true,
+  };
+}
+
+function createSceneState() {
+  return {
+    role: 'pending',
+    hostedRoom: null,
+    pendingElapsed: 0,
+    registeredHostCallbacks: false,
+  };
+}
+
+function currentRoomInfo(sceneState) {
+  return aura.multiplayer.getRoomInfo() || sceneState.hostedRoom || null;
+}
+
+function currentRoomCode(sceneState) {
+  const roomInfo = currentRoomInfo(sceneState);
+  if (roomInfo && roomInfo.code) {
+    return roomInfo.code;
+  }
+  if (LAUNCH_JOIN_CODE) {
+    return LAUNCH_JOIN_CODE;
+  }
+  return ROOM_CONFIG.roomCode;
+}
+
+function readInput() {
+  return {
+    dx: axisFromKeys(aura.input, ['arrowleft', 'a'], ['arrowright', 'd']),
+    dy: axisFromKeys(aura.input, ['arrowup', 'w'], ['arrowdown', 's']),
+  };
+}
+
+function currentStatusLine(sceneState, roomCode) {
+  if (sceneState.role === 'pending') {
+    if (launchedViaExplicitJoin()) {
+      return `Joining room code ${roomCode}...`;
+    }
+    return 'Checking for a room-code match before hosting this room...';
+  }
+  if (sceneState.role === 'host') {
+    if (usesInternetBackedHosting()) {
+      return `Share this room code anywhere: npm run join -- ${roomCode}`;
+    }
+    return `Second terminal: npm run join -- ${roomCode}`;
+  }
+  if (usesInternetBackedHosting()) {
+    return 'Joined through room-code lookup. Direct UDP first, relay fallback ready.';
+  }
+  return 'Joined through the local-first room-code multiplayer flow.';
+}
+
+export function createGameplayScene(context = {}) {
+  const appState = context.appState && typeof context.appState === 'object'
+    ? context.appState
+    : (context.appState = {});
+  const multiplayerSession = ensureSessionState(appState, 'localMultiplayer', createSessionSeed());
+  const multiplayerUi = ensureUiState(appState, 'localMultiplayerHud', createUiSeed());
+  const sceneState = createSceneState();
+
+  function syncSessionState() {
+    const roomInfo = currentRoomInfo(sceneState);
+    multiplayerSession.lastRole = sceneState.role;
+    multiplayerSession.lastRoomCode = roomInfo?.code || ROOM_CONFIG.roomCode;
+    multiplayerSession.lastRoomName = roomInfo?.name || ROOM_CONFIG.roomName;
+    multiplayerSession.lastPlayerCount = Number(aura.multiplayer.getPlayerCount?.() || 0);
+    multiplayerSession.lastConnected = aura.multiplayer.isConnected() === true;
+    multiplayerSession.lastSceneId = 'gameplay';
+  }
+
+  function syncHud() {
+    const roomInfo = currentRoomInfo(sceneState);
+    const roomCode = currentRoomCode(sceneState);
+    const diagnostics = DIAGNOSTICS_CONFIG.enabled
+      ? {
+          mode: roomInfo?.requestedMode || CONNECTIVITY_CONFIG.mode,
+          scope: roomInfo?.scope || (usesInternetBackedHosting() ? 'internet' : 'local'),
+          transportPath: roomInfo?.transportPath || (usesInternetBackedHosting() ? 'internet_pending' : 'local_room'),
+          transportStatus: roomInfo?.transportStatus || (aura.multiplayer.isConnected() ? 'connected' : 'waiting'),
+          joinPath: roomInfo?.joinPath || (usesInternetBackedHosting() ? 'internet_fallback' : 'local'),
+          lastReasonCode: roomInfo?.lastReasonCode || null,
+          pingMs: Number(aura.multiplayer.getPing?.()),
+        }
+      : null;
+    context.setHudScreen?.('hud', {
+      role: sceneState.role === 'pending' ? 'WAITING' : sceneState.role.toUpperCase(),
+      roomCode,
+      roomName: roomInfo?.name || ROOM_CONFIG.roomName,
+      playerCount: Number(aura.multiplayer.getPlayerCount?.() || 0),
+      connected: aura.multiplayer.isConnected() === true,
+      showControlsHint: multiplayerUi.showControlsHint !== false,
+      statusLine: currentStatusLine(sceneState, roomCode),
+      diagnostics,
+    });
+  }
+
+  function ensureHostCallbacks() {
+    if (sceneState.registeredHostCallbacks) return;
+    sceneState.registeredHostCallbacks = true;
+
+    aura.multiplayer.onPlayerJoin((player) => {
+      if (!player || !Number.isFinite(player.id)) return;
+      aura.multiplayer.setState(`player_${player.id}`, createLocalPlayerState(player.id, `p${player.id}`));
+    });
+
+    aura.multiplayer.onPlayerLeave((player) => {
+      if (!player || !Number.isFinite(player.id)) return;
+      const key = `player_${player.id}`;
+      const current = aura.multiplayer.getState(key) || createLocalPlayerState(player.id, `p${player.id}`);
+      aura.multiplayer.setState(key, { ...current, hidden: true });
+    });
+  }
+
+  function activateHost() {
+    if (sceneState.role === 'host') return;
+    const hostOptions = {
+      port: LOCAL_MULTIPLAYER_CONFIG.port,
+      roomCode: ROOM_CONFIG.roomCode,
+      name: ROOM_CONFIG.roomName,
+      maxPlayers: LOCAL_MULTIPLAYER_CONFIG.maxPlayers,
+      internetMode: CONNECTIVITY_CONFIG.mode,
+    };
+    if (CONNECTIVITY_CONFIG.relayHost) {
+      hostOptions.relay = CONNECTIVITY_CONFIG.relayHost;
+    }
+    if (CONNECTIVITY_CONFIG.coordinatorUrl) {
+      hostOptions.coordinatorUrl = CONNECTIVITY_CONFIG.coordinatorUrl;
+    }
+    if (CONNECTIVITY_CONFIG.relayUrl) {
+      hostOptions.relayUrl = CONNECTIVITY_CONFIG.relayUrl;
+    }
+    sceneState.hostedRoom = aura.multiplayer.host(hostOptions);
+    sceneState.role = 'host';
+    ensureHostCallbacks();
+    aura.multiplayer.setState('player_0', createLocalPlayerState(0, 'host'));
+  }
+
+  function resetRun() {
+    sceneState.role = 'pending';
+    sceneState.hostedRoom = null;
+    sceneState.pendingElapsed = 0;
+    sceneState.registeredHostCallbacks = false;
+    multiplayerSession.runsStarted += 1;
+    multiplayerUi.showControlsHint = true;
+    syncSessionState();
+    syncHud();
+  }
+
+  return {
+    id: 'gameplay',
+    playerPrefabId: 'player',
+    hudScreenId: 'hud',
+    dataFiles: [
+      'aura.config.json',
+      'config/gameplay/local-multiplayer.config.js',
+      'content/gameplay/room-layout.js',
+    ],
+    summary: 'Room-code multiplayer starter. `npm run dev` hosts, `npm run join -- CODE` joins, `aura.config.json -> multiplayer` owns room/connectivity defaults, and the HUD surfaces live transport diagnostics.',
+
+    setup() {
+      assertLocalMultiplayerCapabilities();
+      aura.multiplayer.configure({
+        maxPlayers: LOCAL_MULTIPLAYER_CONFIG.maxPlayers,
+        tickRate: LOCAL_MULTIPLAYER_CONFIG.tickRate,
+        protocol: LOCAL_MULTIPLAYER_CONFIG.protocol,
+      });
+      resetRun();
+      console.log('{{PROJECT_TITLE}} room-code multiplayer starter ready');
+    },
+
+    update(dt) {
+      const frameDt = Math.max(0, Number(dt) || 0);
+      const input = readInput();
+      if (input.dx !== 0 || input.dy !== 0) {
+        multiplayerUi.showControlsHint = false;
+      }
+
+      if (sceneState.role === 'pending') {
+        sceneState.pendingElapsed += frameDt;
+        if (aura.multiplayer.isConnected()) {
+          sceneState.role = 'client';
+        } else if (!launchedViaExplicitJoin() && sceneState.pendingElapsed >= resolveHostFallbackSeconds()) {
+          activateHost();
+        }
+      }
+
+      if (sceneState.role === 'host') {
+        const hostState = aura.multiplayer.getState('player_0') || createLocalPlayerState(0, 'host');
+        aura.multiplayer.setState('player_0', applyLocalPlayerMovement(hostState, input, frameDt));
+
+        const inputs = aura.multiplayer.getAllPlayerInputs() || {};
+        for (const [playerId, playerInput] of Object.entries(inputs)) {
+          const numericId = Number(playerId);
+          const key = `player_${playerId}`;
+          const current = aura.multiplayer.getState(key) || createLocalPlayerState(numericId, `p${playerId}`);
+          aura.multiplayer.setState(key, applyLocalPlayerMovement(current, playerInput, frameDt));
+        }
+      } else if (sceneState.role === 'client' && aura.multiplayer.isConnected()) {
+        aura.multiplayer.sendInput(input);
+      }
+
+      syncSessionState();
+      syncHud();
+    },
+
+    onExit() {
+      context.clearHudScreen?.();
+    },
+
+    draw() {
+      aura.draw2d.clear(aura.rgb(0.07, 0.09, 0.13));
+
+      const allState = aura.multiplayer.getAllState() || {};
+      for (const key of Object.keys(allState).sort()) {
+        drawLocalPlayerState(allState[key], key);
+      }
+    },
+
+    getState() {
+      return {
+        role: sceneState.role,
+        pendingElapsed: sceneState.pendingElapsed,
+        hostedRoom: sceneState.hostedRoom
+          ? {
+              code: sceneState.hostedRoom.code || null,
+              name: sceneState.hostedRoom.name || null,
+              port: sceneState.hostedRoom.port || null,
+            }
+          : null,
+      };
+    },
+
+    notes: [
+      'Keep the room-code multiplayer dev loop starter-owned here instead of splitting it between src/main.js and layout-generated files.',
+      'Use appState.session for durable room/session summary, appState.ui for HUD presentation state, and keep connection-side details scene-local.',
+      'aura.config.json -> multiplayer is the project-level source of truth for room code, room name, diagnostics, and relay defaults.',
+      'config/gameplay/local-multiplayer.config.js stays focused on local gameplay tuning like port, player speed, bounds, and fallback timing.',
+    ],
+  };
+}
+
+export default createGameplayScene;

package/templates/create/local-multiplayer/src/main.js

@@ -0,0 +1,17 @@
+// {{PROJECT_TITLE}} - AuraJS local multiplayer starter bootstrap
+
+import { createApp } from './runtime/app.js';
+
+const app = createApp();
+
+aura.setup = function () {
+  app.setup();
+};
+
+aura.update = function (dt) {
+  app.update(dt);
+};
+
+aura.draw = function () {
+  app.draw();
+};

package/templates/create/local-multiplayer/src/runtime/capabilities.js

@@ -0,0 +1,28 @@
+function hasMethod(obj, method) {
+  return Boolean(obj) && typeof obj[method] === 'function';
+}
+
+export function assertRuntimeCapabilities() {
+  const missing = [];
+  if (!hasMethod(aura.input, 'isKeyDown')) missing.push('aura.input.isKeyDown');
+  if (!hasMethod(aura.draw2d, 'clear')) missing.push('aura.draw2d.clear');
+  if (!hasMethod(aura.draw2d, 'rectFill')) missing.push('aura.draw2d.rectFill');
+  if (!hasMethod(aura.draw2d, 'text')) missing.push('aura.draw2d.text');
+  if (typeof aura.rgb !== 'function') missing.push('aura.rgb');
+  if (!hasMethod(aura.multiplayer, 'configure')) missing.push('aura.multiplayer.configure');
+  if (!hasMethod(aura.multiplayer, 'getAllPlayerInputs')) missing.push('aura.multiplayer.getAllPlayerInputs');
+  if (!hasMethod(aura.multiplayer, 'getAllState')) missing.push('aura.multiplayer.getAllState');
+  if (!hasMethod(aura.multiplayer, 'getPlayerCount')) missing.push('aura.multiplayer.getPlayerCount');
+  if (!hasMethod(aura.multiplayer, 'getRoomInfo')) missing.push('aura.multiplayer.getRoomInfo');
+  if (!hasMethod(aura.multiplayer, 'getState')) missing.push('aura.multiplayer.getState');
+  if (!hasMethod(aura.multiplayer, 'host')) missing.push('aura.multiplayer.host');
+  if (!hasMethod(aura.multiplayer, 'isConnected')) missing.push('aura.multiplayer.isConnected');
+  if (!hasMethod(aura.multiplayer, 'onPlayerJoin')) missing.push('aura.multiplayer.onPlayerJoin');
+  if (!hasMethod(aura.multiplayer, 'onPlayerLeave')) missing.push('aura.multiplayer.onPlayerLeave');
+  if (!hasMethod(aura.multiplayer, 'sendInput')) missing.push('aura.multiplayer.sendInput');
+  if (!hasMethod(aura.multiplayer, 'setState')) missing.push('aura.multiplayer.setState');
+
+  if (missing.length > 0) {
+    throw new Error(`[local-multiplayer-template] runtime missing required APIs: ${missing.join(', ')} [reason:missing_runtime_api]`);
+  }
+}

package/templates/create/local-multiplayer/ui/hud.screen.js

@@ -0,0 +1,60 @@
+import { LOCAL_MULTIPLAYER_CONFIG } from '../config/gameplay/local-multiplayer.config.js';
+import { ROOM_LAYOUT } from '../content/gameplay/room-layout.js';
+
+const hudScreen = {
+  id: 'hud',
+  kind: 'ui-screen',
+  role: 'hud',
+  draw: drawLocalMultiplayerHud,
+  notes: [
+    'Keep multiplayer room status and join guidance in the authored HUD instead of baking it into src/main.js.',
+    'This starter keeps room-code guidance in one place and makes the local-first default plus the one-field relay upgrade path explicit in authored copy.',
+  ],
+};
+
+export function createHudScreen() {
+  return hudScreen;
+}
+
+export function drawLocalMultiplayerHud({
+  role = 'WAITING',
+  roomCode = ROOM_LAYOUT.roomCode,
+  roomName = ROOM_LAYOUT.roomName,
+  playerCount = 0,
+  connected = false,
+  showControlsHint = true,
+  statusLine = '',
+  diagnostics = null,
+} = {}) {
+  aura.draw2d.text('{{PROJECT_TITLE}} Multiplayer', 18, 16, 18, aura.rgb(0.97, 0.94, 0.82));
+  aura.draw2d.text(`Role: ${role}`, 18, 42, 12, aura.rgb(0.84, 0.92, 0.98));
+  aura.draw2d.text(`Room code: ${roomCode}`, 18, 58, 12, aura.rgb(0.84, 0.92, 0.98));
+  aura.draw2d.text(`Players: ${playerCount}`, 18, 74, 12, aura.rgb(0.8, 0.92, 0.84));
+  aura.draw2d.text(statusLine, 18, 104, 11, aura.rgb(0.92, 0.88, 0.76));
+  aura.draw2d.text(`Room name: ${roomName}`, 18, 122, 11, aura.rgb(0.8, 0.86, 0.96));
+
+  if (showControlsHint) {
+    aura.draw2d.text('Move: Arrow keys / WASD', 18, LOCAL_MULTIPLAYER_CONFIG.height - 46, 11, aura.rgb(0.78, 0.9, 0.84));
+  }
+
+  if (diagnostics && typeof diagnostics === 'object') {
+    const pingLabel = Number.isFinite(diagnostics.pingMs) ? `${Math.round(diagnostics.pingMs)} ms` : '-';
+    aura.draw2d.text(`Mode: ${diagnostics.mode || '-'}`, LOCAL_MULTIPLAYER_CONFIG.width - 248, 42, 11, aura.rgb(0.82, 0.9, 0.86));
+    aura.draw2d.text(`Path: ${diagnostics.transportPath || '-'}`, LOCAL_MULTIPLAYER_CONFIG.width - 248, 58, 11, aura.rgb(0.82, 0.9, 0.86));
+    aura.draw2d.text(`Status: ${diagnostics.transportStatus || '-'}`, LOCAL_MULTIPLAYER_CONFIG.width - 248, 74, 11, aura.rgb(0.82, 0.9, 0.86));
+    aura.draw2d.text(`Join: ${diagnostics.joinPath || '-'}`, LOCAL_MULTIPLAYER_CONFIG.width - 248, 90, 11, aura.rgb(0.82, 0.9, 0.86));
+    aura.draw2d.text(`Ping: ${pingLabel}`, LOCAL_MULTIPLAYER_CONFIG.width - 248, 106, 11, aura.rgb(0.82, 0.9, 0.86));
+    aura.draw2d.text(`Reason: ${diagnostics.lastReasonCode || '-'}`, LOCAL_MULTIPLAYER_CONFIG.width - 248, 122, 11, aura.rgb(0.82, 0.9, 0.86));
+  }
+
+  aura.draw2d.text(
+    'Room-code multiplayer. Put room + relay defaults in aura.config.json -> multiplayer.',
+    18,
+    LOCAL_MULTIPLAYER_CONFIG.height - 28,
+    10,
+    aura.rgb(0.76, 0.82, 0.92),
+  );
+  aura.draw2d.text(`Connected: ${connected}`, LOCAL_MULTIPLAYER_CONFIG.width - 166, 16, 11, aura.rgb(0.82, 0.9, 0.86));
+}
+
+export default hudScreen;