playcademy 0.12.1 → 0.12.3

package/dist/index.js

@@ -5246,9 +5246,23 @@ async function bundleBackend(config, options = {}) {
   const monorepoEdgeSrc = join6(monorepoRoot, "packages/edge-play/src");
   const isBuiltPackage = existsSync7(embeddedEdgeSrc);
   const edgePlaySrc = isBuiltPackage ? embeddedEdgeSrc : monorepoEdgeSrc;
-  const cliPackageRoot = isBuiltPackage ? join6(distDir, "../..") : join6(monorepoRoot, "packages/cli");
-  const cliNodeModules = isBuiltPackage ? cliPackageRoot : monorepoRoot;
+  const cliPackageRoot = isBuiltPackage ? join6(distDir, "../../..") : join6(monorepoRoot, "packages/cli");
+  const cliNodeModules = isBuiltPackage ? join6(cliPackageRoot, "node_modules") : monorepoRoot;
   const workspaceNodeModules = join6(workspace, "node_modules");
+  const constantsEntry = isBuiltPackage ? (
+    // dist/edge-play/src → dist/vendor/constants/index.ts
+    join6(embeddedEdgeSrc, "..", "..", "vendor", "constants", "index.ts")
+  ) : join6(monorepoRoot, "packages", "constants", "src", "index.ts");
+  console.log({
+    isBuiltPackage,
+    distDir,
+    constantsEntry,
+    embeddedEdgeSrc,
+    edgePlaySrc,
+    cliPackageRoot,
+    cliNodeModules,
+    workspaceNodeModules
+  });
   const result = await esbuild.build({
     stdin: {
       contents: entryCode,
@@ -5264,12 +5278,17 @@ async function bundleBackend(config, options = {}) {
     sourcemap: options.sourcemap ? "inline" : false,
     minify: options.minify || false,
     logLevel: "error",
-    nodePaths: [workspaceNodeModules, cliNodeModules],
-    // Check workspace first, then CLI
+    nodePaths: [workspaceNodeModules, cliNodeModules, join6(cliPackageRoot, "..")],
+    // Check workspace first, then CLI package and project root
+    loader: {
+      ".ts": "ts"
+    },
     define: {
       PLAYCADEMY_CONFIG: JSON.stringify(bundleConfig)
     },
     alias: {
+      // Map workspace-only package to embedded constants for published CLI
+      "@playcademy/constants": constantsEntry,
       /**
        * @game-api alias maps to the user's custom routes directory
        *
@@ -7541,7 +7560,7 @@ async function startDevServer(options) {
     platformUrl = process.env.PLAYCADEMY_BASE_URL || "http://localhost:5174"
   } = options;
   const hasSandboxTimebackCreds = !!process.env.TIMEBACK_API_CLIENT_ID;
-  const devConfig = config.integrations?.timeback && !hasSandboxTimebackCreds ? { ...config, integrations: { ...config.integrations, timeback: void 0 } } : config;
+  const devConfig = config?.integrations?.timeback && !hasSandboxTimebackCreds ? { ...config, integrations: { ...config.integrations, timeback: void 0 } } : config;
   const bundle = await bundleBackend(devConfig, {
     sourcemap: false,
     minify: false

package/dist/utils.js

@@ -1186,9 +1186,23 @@ async function bundleBackend(config, options = {}) {
   const monorepoEdgeSrc = join2(monorepoRoot, "packages/edge-play/src");
   const isBuiltPackage = existsSync2(embeddedEdgeSrc);
   const edgePlaySrc = isBuiltPackage ? embeddedEdgeSrc : monorepoEdgeSrc;
-  const cliPackageRoot = isBuiltPackage ? join2(distDir, "../..") : join2(monorepoRoot, "packages/cli");
-  const cliNodeModules = isBuiltPackage ? cliPackageRoot : monorepoRoot;
+  const cliPackageRoot = isBuiltPackage ? join2(distDir, "../../..") : join2(monorepoRoot, "packages/cli");
+  const cliNodeModules = isBuiltPackage ? join2(cliPackageRoot, "node_modules") : monorepoRoot;
   const workspaceNodeModules = join2(workspace, "node_modules");
+  const constantsEntry = isBuiltPackage ? (
+    // dist/edge-play/src → dist/vendor/constants/index.ts
+    join2(embeddedEdgeSrc, "..", "..", "vendor", "constants", "index.ts")
+  ) : join2(monorepoRoot, "packages", "constants", "src", "index.ts");
+  console.log({
+    isBuiltPackage,
+    distDir,
+    constantsEntry,
+    embeddedEdgeSrc,
+    edgePlaySrc,
+    cliPackageRoot,
+    cliNodeModules,
+    workspaceNodeModules
+  });
   const result = await esbuild.build({
     stdin: {
       contents: entryCode,
@@ -1204,12 +1218,17 @@ async function bundleBackend(config, options = {}) {
     sourcemap: options.sourcemap ? "inline" : false,
     minify: options.minify || false,
     logLevel: "error",
-    nodePaths: [workspaceNodeModules, cliNodeModules],
-    // Check workspace first, then CLI
+    nodePaths: [workspaceNodeModules, cliNodeModules, join2(cliPackageRoot, "..")],
+    // Check workspace first, then CLI package and project root
+    loader: {
+      ".ts": "ts"
+    },
     define: {
       PLAYCADEMY_CONFIG: JSON.stringify(bundleConfig)
     },
     alias: {
+      // Map workspace-only package to embedded constants for published CLI
+      "@playcademy/constants": constantsEntry,
       /**
        * @game-api alias maps to the user's custom routes directory
        *
@@ -1298,7 +1317,7 @@ async function startDevServer(options) {
     platformUrl = process.env.PLAYCADEMY_BASE_URL || "http://localhost:5174"
   } = options;
   const hasSandboxTimebackCreds = !!process.env.TIMEBACK_API_CLIENT_ID;
-  const devConfig = config.integrations?.timeback && !hasSandboxTimebackCreds ? { ...config, integrations: { ...config.integrations, timeback: void 0 } } : config;
+  const devConfig = config?.integrations?.timeback && !hasSandboxTimebackCreds ? { ...config, integrations: { ...config.integrations, timeback: void 0 } } : config;
   const bundle = await bundleBackend(devConfig, {
     sourcemap: false,
     minify: false

package/dist/vendor/constants/auth.ts

@@ -0,0 +1,13 @@
+/**
+ * Authentication Constants
+ *
+ * Constants related to authentication providers.
+ */
+
+/**
+ * Auth Provider Constants
+ */
+export const AUTH_PROVIDER_IDS = {
+    TIMEBACK: 'timeback',
+    TIMEBACK_LTI: 'timeback-lti',
+} as const

package/dist/vendor/constants/domains.ts

@@ -0,0 +1,43 @@
+/**
+ * Domain and URL Constants
+ *
+ * Centralized domain names and base URLs for the Playcademy platform.
+ * These constants are shared across multiple packages to ensure consistency.
+ */
+
+/**
+ * Playcademy domain names
+ */
+export const PLAYCADEMY_DOMAINS = {
+    /** Primary domain (hub, landing pages) */
+    apex: 'playcademy.net',
+    /** Marketing/alternative domain */
+    apexAlt: 'playcademy.com',
+    /** Game backend worker domain */
+    games: 'playcademy.gg',
+} as const
+
+/**
+ * Platform hub base URLs by environment
+ * Used by CLI, SDK, and other packages to make API requests
+ */
+export const PLAYCADEMY_BASE_URLS = {
+    production: 'https://hub.playcademy.net',
+    staging: 'https://hub.dev.playcademy.net',
+} as const
+
+/**
+ * Game backend worker domains by environment
+ * Workers are deployed to Cloudflare and accessible at:
+ * - Production: {slug}.playcademy.gg
+ * - Staging: {slug}-staging.playcademy.gg
+ */
+export const GAME_WORKER_DOMAINS = {
+    production: 'playcademy.gg',
+    staging: 'staging.playcademy.gg',
+} as const
+
+/**
+ * Type exports
+ */
+export type PlatformEnvironment = 'production' | 'staging'

package/dist/vendor/constants/env-vars.ts

@@ -0,0 +1,20 @@
+/**
+ * Environment Variable Names
+ *
+ * Centralized environment variable names used across the platform.
+ * These ensure consistency between deployers and runtime environments.
+ */
+
+/**
+ * Environment variables for game backend workers
+ * Used by both the deployment system (@playcademy/api-core)
+ * and the worker runtime (@playcademy/edge-play)
+ */
+export const WORKER_ENV_VARS = {
+    /** Game-specific API key for calling platform API */
+    PLAYCADEMY_API_KEY: 'PLAYCADEMY_API_KEY',
+    /** Game ID (UUID) */
+    GAME_ID: 'GAME_ID',
+    /** Platform API base URL */
+    PLAYCADEMY_BASE_URL: 'PLAYCADEMY_BASE_URL',
+} as const

package/dist/vendor/constants/index.ts

@@ -0,0 +1,15 @@
+/**
+ * @playcademy/constants
+ *
+ * Centralized constants shared across the Playcademy platform.
+ * This package contains domain names, URLs, environment variable names,
+ * and other constants that need to be consistent across multiple packages.
+ */
+
+export * from './auth'
+export * from './domains'
+export * from './env-vars'
+export * from './overworld'
+export * from './system'
+export * from './timeback'
+export * from './workers'

package/dist/vendor/constants/overworld.ts

@@ -0,0 +1,327 @@
+/**
+ * Overworld & Game Constants
+ *
+ * All constants related to the game world, including items, rendering,
+ * maps, physics, UI, and core platform games.
+ */
+
+// ═══════════════════════════════════════════════════════════════════════
+// VIEWPORT & LEVEL SYSTEM
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Minimum viewport dimensions for the game
+ */
+export const MIN_VIEWPORT_WIDTH = 960
+export const MIN_VIEWPORT_HEIGHT = 640
+
+/**
+ * Maximum player level
+ */
+export const MAX_LEVEL = 100
+
+// ═══════════════════════════════════════════════════════════════════════
+// ITEMS & ECONOMY
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Item Slugs - Canonical slugs for core platform items
+ */
+export const ITEM_SLUGS = {
+    /** Primary platform currency */
+    PLAYCADEMY_CREDITS: 'PLAYCADEMY_CREDITS',
+
+    /** Experience points currency */
+    PLAYCADEMY_XP: 'PLAYCADEMY_XP',
+
+    /** Core platform badges */
+    FOUNDING_MEMBER_BADGE: 'FOUNDING_MEMBER_BADGE',
+    EARLY_ADOPTER_BADGE: 'EARLY_ADOPTER_BADGE',
+    FIRST_GAME_BADGE: 'FIRST_GAME_BADGE',
+
+    /** Example items */
+    COMMON_SWORD: 'COMMON_SWORD',
+    SMALL_HEALTH_POTION: 'SMALL_HEALTH_POTION',
+    SMALL_BACKPACK: 'SMALL_BACKPACK',
+
+    /** Placeable items */
+    LAVA_LAMP: 'LAVA_LAMP',
+    BOOMBOX: 'BOOMBOX',
+    CABIN_BED: 'CABIN_BED',
+} as const
+
+/**
+ * Currency-specific constants for easier access
+ */
+export const CURRENCIES = {
+    /** Primary platform currency slug */
+    PRIMARY: ITEM_SLUGS.PLAYCADEMY_CREDITS,
+
+    /** Experience points slug */
+    XP: ITEM_SLUGS.PLAYCADEMY_XP,
+} as const
+
+/**
+ * Currency symbol constants
+ */
+export const CURRENCY_SYMBOLS = {
+    /** Primary platform currency symbol */
+    PLAYCADEMY_CREDITS: 'PC',
+
+    /** Experience points symbol */
+    PLAYCADEMY_XP: 'XP',
+
+    /** Default currency symbol */
+    DEFAULT: '¤',
+} as const
+
+/**
+ * Badge constants for easier access
+ */
+export const BADGES = {
+    FOUNDING_MEMBER: ITEM_SLUGS.FOUNDING_MEMBER_BADGE,
+    EARLY_ADOPTER: ITEM_SLUGS.EARLY_ADOPTER_BADGE,
+    FIRST_GAME: ITEM_SLUGS.FIRST_GAME_BADGE,
+} as const
+
+// ═══════════════════════════════════════════════════════════════════════
+// RENDERING & VISUALS
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Sprite System Constants
+ */
+export const SPRITE_COMPONENTS = ['body', 'outfit', 'hairstyle', 'eyes', 'accessory'] as const
+export const SPRITE_LAYER_ORDER = ['body', 'outfit', 'hairstyle', 'eyes', 'accessory'] as const
+
+/**
+ * Renderer Z-layer constants – centralised depth values used by the Three.js
+ * front-end so magic numbers aren't scattered around the codebase.
+ */
+export const Z_LAYERS = {
+    /** Depth step between successive Tiled tile-layers (background → foreground). */
+    TILE_LAYER_STEP: 0.01,
+
+    /** Depth step between stacked sprite components inside a single character. */
+    SPRITE_COMPONENT_STEP: 0.002,
+
+    /** Minimum Z for Y-sorted entities (top of screen). */
+    ENTITY_MIN: 0.011,
+
+    /** Maximum Z for Y-sorted entities (bottom of screen). */
+    ENTITY_MAX: 0.0115,
+
+    /** Fallback Z when map bounds are unavailable. */
+    ENTITY_FALLBACK: 0.01125,
+
+    /** Offset applied to placeable item sprites so they sit above characters. */
+    PLACEABLE_OFFSET: 0.012,
+
+    /** Shadow offset below entity base Z (shadows appear below characters). */
+    SHADOW_OFFSET: -0.001,
+} as const
+
+/**
+ * Shadow constants
+ */
+export const SHADOW_CONSTANTS = {
+    /** Shadow radius as a fraction of tileWidth */
+    RADIUS_MULTIPLIER: 0.4,
+
+    /** Y offset in world units as a fraction of one tile width. */
+    Y_OFFSET_TILES: -0.9,
+
+    /** Shadow opacity (semi-transparent) */
+    OPACITY: 0.4,
+
+    /** Y-axis scale for elliptical perspective */
+    Y_SCALE: 0.6,
+
+    /** Minimum shadow size during jumps (30% of original) */
+    SCALE_MIN: 0.1,
+
+    /** Maximum jump height for scaling calculations */
+    MAX_JUMP_HEIGHT: 100,
+} as const
+
+/**
+ * Nameplate constants
+ */
+export const NAMEPLATE_CONSTANTS = {
+    /** Adjust nameplate position from base height */
+    BASE_Y_ADJUST: -1,
+    /** Extra pixels to raise when a head accessory is equipped */
+    HEAD_ACCESSORY_EXTRA_PX: 5,
+    /** Available background colors for nameplates */
+    BACKGROUND_COLORS: [
+        '#2d3748', // Default gray
+        '#dc2626', // Red
+        '#ea580c', // Orange
+        '#ca8a04', // Amber
+        '#16a34a', // Green
+        '#0891b2', // Cyan
+        '#2563eb', // Blue
+        '#7c3aed', // Purple
+        '#c026d3', // Pink
+        '#e11d48', // Rose
+        '#134e4a', // Dark teal
+        '#831843', // Dark pink
+    ],
+    /** Default background color */
+    DEFAULT_BACKGROUND_COLOR: '#2d3748',
+} as const
+
+/**
+ * Particle system constants
+ */
+export const LANDING_PARTICLES = {
+    /** Number of particles per landing */
+    COUNT: 6,
+
+    /** Base duration in ms */
+    DURATION: 500,
+
+    /** Spread radius as fraction of tileWidth */
+    SPREAD: 0.4,
+
+    /** Dust particle color */
+    COLOR: '#777',
+
+    /** Particle size in pixels in the game world */
+    SIZE: 3,
+
+    /** Vertical offset as a fraction of tile width (world units). */
+    Y_OFFSET_TILES: -0.9,
+} as const
+
+// ═══════════════════════════════════════════════════════════════════════
+// MAPS
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Map System Constants
+ */
+export const MAP_CONSTANTS = {
+    /** Name of the Tiled layer containing map entry points */
+    ENTRY_POINT_LAYER_NAME: 'EntryPoints',
+
+    /** Name of the Tiled layer containing collision objects */
+    COLLISION_LAYER_NAME: 'Object Layer 1',
+
+    /** Name of the Tiled layer containing placeable objects */
+    PLACEABLE_AREA_LAYER_NAME: 'PlaceableArea',
+
+    /** Base path for tilesets */
+    TILESET_BASE_PATH: '/public/tilesets',
+} as const
+
+// ═══════════════════════════════════════════════════════════════════════
+// PHYSICS & MOVEMENT
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Player movement and physics constants
+ */
+export const PLAYER_PHYSICS = {
+    /** Initial upward velocity when jumping (pixels per second) */
+    JUMP_FORCE: 150,
+
+    /** Downward acceleration due to gravity (pixels per second^2) */
+    GRAVITY: -450,
+} as const
+
+/**
+ * Bunny hop (jump queuing) constants – Counter-Strike style mechanics.
+ */
+export const BUNNY_HOP = {
+    /** Base time window (ms) within which a queued jump is valid. */
+    QUEUE_WINDOW_MS: 100,
+
+    /** Downward velocity threshold (px/s) to allow jump queuing. */
+    FALL_SPEED_THRESHOLD: -50,
+
+    /** Vertical offset threshold (px) to allow queuing close to ground. */
+    CLOSE_TO_GROUND_THRESHOLD: 30,
+
+    /** Speed increase per successful hop. */
+    SPEED_INCREMENT: 0.15,
+
+    /** Maximum total speed multiplier. */
+    MAX_SPEED_MULTIPLIER: 5,
+
+    /** Multiplier applied to jump force on chained hops (slightly lower). */
+    HOP_JUMP_FORCE_MULTIPLIER: 0.95,
+} as const
+
+// ═══════════════════════════════════════════════════════════════════════
+// UI & UX
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Audio defaults
+ */
+export const AUDIO_DEFAULTS = {
+    /** Master output volume */
+    MASTER_VOLUME: 0.5,
+
+    /** Background music enabled by default */
+    MUSIC_ENABLED: true,
+    /** Background music volume */
+    MUSIC_VOLUME: 0.5,
+
+    /** Sound effects enabled by default */
+    SFX_ENABLED: true,
+    /** Sound effects volume */
+    SFX_VOLUME: 0.5,
+} as const
+
+/**
+ * Toast Duration Constants
+ * Centralized toast notification display durations in milliseconds.
+ */
+export const TOAST_DURATION = {
+    /** Short duration for simple confirmations */
+    SHORT: 3000,
+
+    /** Standard duration for most notifications */
+    STANDARD: 5000,
+
+    /** Long duration for important notifications */
+    LONG: 8000,
+
+    /** Error message duration */
+    ERROR: 4000,
+} as const
+
+/**
+ * Cache Control Headers
+ * Centralized cache control strategies for different asset types and API responses.
+ */
+export const CACHE_CONTROL = {
+    /** Immutable assets with content-based versioning (sprites, audio, etc.) */
+    IMMUTABLE: 'public, max-age=31536000, immutable',
+
+    /** JSON data - cached for 1 day in browser, 1 year in CDN */
+    JSON_DATA: 'public, max-age=86400, s-maxage=31536000, must-revalidate',
+
+    /** Character components API - cached for 1 hour in browser, 3 hours in CDN */
+    API_CHARACTER_COMPONENTS: 'public, max-age=21600, s-maxage=21600, stale-while-revalidate=3600',
+
+    /** Level configs API - cached for 1 hour in browser, 12 hours in CDN */
+    API_LEVEL_CONFIGS: 'public, max-age=3600, s-maxage=86400, stale-while-revalidate=120',
+
+    /** Sprite templates API - cached for 1 day in browser, 1 week in CDN */
+    API_SPRITE_TEMPLATES: 'public, max-age=86400, s-maxage=86400, stale-while-revalidate=3600',
+} as const
+
+// ═══════════════════════════════════════════════════════════════════════
+// CORE PLATFORM GAMES
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Core Game UUIDs - Canonical UUIDs for core platform games
+ */
+export const CORE_GAME_UUIDS = {
+    /** Internal playground game for development and testing */
+    PLAYGROUND: '00000000-0000-0000-0000-000000000001',
+} as const

package/dist/vendor/constants/system.ts

@@ -0,0 +1,10 @@
+/**
+ * System-Level Platform Constants
+ *
+ * Core platform settings that affect the entire system.
+ */
+
+/**
+ * Timezone for platform-wide operations
+ */
+export const PLATFORM_TIMEZONE = 'America/New_York' as const

package/dist/vendor/constants/timeback.ts

@@ -0,0 +1,32 @@
+/**
+ * TimeBack Integration Constants
+ *
+ * Constants related to TimeBack Caliper integration.
+ */
+
+/**
+ * TimeBack Caliper sensor URLs
+ * Allowed sensor URLs for Caliper event validation
+ */
+export const TIMEBACK_CALIPER_SENSORS = [
+    'https://samuraimath.com',
+    'https://app.alphamath.school',
+    'https://mathraiders.com',
+] as const
+
+/**
+ * TimeBack integration route paths (on game backend)
+ * These routes are available on game backends when TimeBack is enabled
+ *
+ * NOTE:
+ *  These paths are relative to /api/ - the full paths are /api/integrations/timeback/*
+ */
+export const TIMEBACK_ROUTES = {
+    END_ACTIVITY: '/integrations/timeback/end-activity',
+} as const
+
+/**
+ * TimeBack OneRoster organization identifier
+ * This is the default organization sourcedId for Playcademy games
+ */
+export const TIMEBACK_ORG_SOURCED_ID = 'PLAYCADEMY' as const

package/dist/vendor/constants/workers.ts

@@ -0,0 +1,21 @@
+/**
+ * Worker Naming Constants
+ *
+ * Conventions for naming Cloudflare workers to avoid collisions
+ * between staging and production deployments.
+ */
+
+/**
+ * Worker naming patterns
+ * - Production workers: {slug} → accessible at {slug}.playcademy.gg
+ * - Staging workers: staging-{slug} → accessible at {slug}-staging.playcademy.gg
+ *
+ * Note: Worker names use a PREFIX (staging-) while hostnames use a SUFFIX (-staging)
+ * to follow subdomain naming conventions.
+ */
+export const WORKER_NAMING = {
+    /** Prefix for staging worker names (e.g., "staging-bamboo") */
+    STAGING_PREFIX: 'staging-',
+    /** Suffix for staging worker hostnames (e.g., "bamboo-staging.playcademy.gg") */
+    STAGING_SUFFIX: '-staging',
+} as const

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "playcademy",
-    "version": "0.12.1",
+    "version": "0.12.3",
     "type": "module",
     "module": "./dist/index.js",
     "main": "./dist/index.js",
@@ -41,7 +41,7 @@
     "dependencies": {
         "@hono/node-server": "^1.19.5",
         "@inquirer/prompts": "^7.8.6",
-        "@playcademy/sdk": "0.1.2",
+        "@playcademy/sdk": "0.1.5",
         "better-sqlite3": "^12.4.1",
         "chokidar": "^4.0.3",
         "colorette": "^2.0.20",