@loonylabs/create-game 0.1.0

package/template/apps/server/src/tests/voxelSandbox.test.ts

@@ -0,0 +1,133 @@
+import { describe, test, expect } from 'vitest';
+import { VoxelChunkCache } from '../voxelChunkCache.js';
+import { createVoxelPlayerPhysics } from '../voxelPlayerState.js';
+import { getTerrainHeight, updatePhysicsBody, updateJumpState, tryJump, snapToGround, consumeJumpBuffer, DEFAULT_PHYSICS_CONFIG, DEFAULT_JUMP_CONFIG } from '@loonylabs/gamedev-core';
+import { SANDBOX_TERRAIN_OPTIONS, SANDBOX_SPAWN } from '../../../game-data/src/voxel/sandbox-terrain-config.js';
+
+const SEED = 42;
+
+function createSandboxEnv() {
+  const cache = new VoxelChunkCache(SEED, SANDBOX_TERRAIN_OPTIONS);
+  const getGroundY = (x: number, z: number) => getTerrainHeight(cache.getChunkFn, x, z);
+  return { cache, getGroundY };
+}
+
+describe('Voxel Sandbox Physics', () => {
+  test('terrain height is queryable at spawn position', () => {
+    const { getGroundY } = createSandboxEnv();
+    const height = getGroundY(SANDBOX_SPAWN.x, SANDBOX_SPAWN.z);
+    expect(height).not.toBeNull();
+    expect(height).toBeGreaterThan(0);
+    expect(height).toBeLessThan(64);
+  });
+
+  test('player spawns at terrain height and is grounded', () => {
+    const { getGroundY } = createSandboxEnv();
+    const spawnHeight = getGroundY(SANDBOX_SPAWN.x, SANDBOX_SPAWN.z)!;
+    const physics = createVoxelPlayerPhysics(SANDBOX_SPAWN.x, spawnHeight, SANDBOX_SPAWN.z);
+
+    expect(physics.body.x).toBe(SANDBOX_SPAWN.x);
+    expect(physics.body.y).toBe(spawnHeight);
+    expect(physics.body.z).toBe(SANDBOX_SPAWN.z);
+    expect(physics.body.isGrounded).toBe(true);
+  });
+
+  test('gravity pulls player to ground when spawned in air', () => {
+    const { getGroundY } = createSandboxEnv();
+    const spawnHeight = getGroundY(SANDBOX_SPAWN.x, SANDBOX_SPAWN.z)!;
+    // Spawn 10 units above terrain
+    const physics = createVoxelPlayerPhysics(SANDBOX_SPAWN.x, spawnHeight + 10, SANDBOX_SPAWN.z);
+    physics.body.isGrounded = false;
+
+    // Simulate ~1 second (20 ticks at 50ms)
+    for (let i = 0; i < 20; i++) {
+      updatePhysicsBody(physics.body, 0.05, getGroundY, DEFAULT_PHYSICS_CONFIG);
+    }
+
+    expect(physics.body.isGrounded).toBe(true);
+    expect(physics.body.y).toBeCloseTo(spawnHeight, 0);
+  });
+
+  test('PLAYER_JUMP makes player airborne then lands', () => {
+    const { getGroundY } = createSandboxEnv();
+    const spawnHeight = getGroundY(SANDBOX_SPAWN.x, SANDBOX_SPAWN.z)!;
+    const physics = createVoxelPlayerPhysics(SANDBOX_SPAWN.x, spawnHeight, SANDBOX_SPAWN.z);
+
+    // Jump
+    const jumped = tryJump(physics.body, physics.jumpState, DEFAULT_JUMP_CONFIG);
+    expect(jumped).toBe(true);
+    expect(physics.body.isGrounded).toBe(false);
+    expect(physics.body.velocityY).toBeGreaterThan(0);
+
+    // Simulate until landing (~2 seconds)
+    for (let i = 0; i < 40; i++) {
+      updateJumpState(physics.jumpState, physics.body, 0.05);
+      updatePhysicsBody(physics.body, 0.05, getGroundY, DEFAULT_PHYSICS_CONFIG);
+    }
+
+    expect(physics.body.isGrounded).toBe(true);
+    expect(physics.body.y).toBeCloseTo(spawnHeight, 0);
+  });
+
+  test('horizontal movement snaps to terrain height for small steps', () => {
+    const { getGroundY } = createSandboxEnv();
+    const spawnHeight = getGroundY(SANDBOX_SPAWN.x, SANDBOX_SPAWN.z)!;
+    const physics = createVoxelPlayerPhysics(SANDBOX_SPAWN.x, spawnHeight, SANDBOX_SPAWN.z);
+
+    // Small step — within snap threshold
+    physics.body.x += 0.2;
+    physics.body.z += 0.2;
+    snapToGround(physics.body, getGroundY, DEFAULT_PHYSICS_CONFIG);
+
+    const newHeight = getGroundY(physics.body.x, physics.body.z);
+    expect(newHeight).not.toBeNull();
+    // For small steps, body should be snapped to terrain
+    if (physics.body.isGrounded) {
+      expect(physics.body.y).toBeCloseTo(newHeight!, 1);
+    } else {
+      // Walked off a cliff — gravity will handle it
+      expect(physics.body.isGrounded).toBe(false);
+    }
+  });
+
+  test('large horizontal step off cliff makes player airborne', () => {
+    const { getGroundY } = createSandboxEnv();
+    const spawnHeight = getGroundY(SANDBOX_SPAWN.x, SANDBOX_SPAWN.z)!;
+    const physics = createVoxelPlayerPhysics(SANDBOX_SPAWN.x, spawnHeight, SANDBOX_SPAWN.z);
+
+    // Move far enough that terrain height differs significantly
+    physics.body.x += 5;
+    physics.body.z += 5;
+    snapToGround(physics.body, getGroundY, DEFAULT_PHYSICS_CONFIG);
+
+    const newHeight = getGroundY(physics.body.x, physics.body.z);
+    expect(newHeight).not.toBeNull();
+    // Either snapped or went airborne — both are valid physics behavior
+    if (Math.abs(spawnHeight - newHeight!) > DEFAULT_PHYSICS_CONFIG.groundSnapThreshold) {
+      // Large height difference — could go airborne
+      expect(true).toBe(true); // physics handled it
+    } else {
+      expect(physics.body.y).toBeCloseTo(newHeight!, 1);
+    }
+  });
+
+  test('entity snapshot includes correct 3D data', () => {
+    const { getGroundY } = createSandboxEnv();
+    const spawnHeight = getGroundY(SANDBOX_SPAWN.x, SANDBOX_SPAWN.z)!;
+    const physics = createVoxelPlayerPhysics(SANDBOX_SPAWN.x, spawnHeight, SANDBOX_SPAWN.z);
+
+    // Simulate what the game loop does for ENTITY_SYNC
+    const snapshot = {
+      entityId: 1,
+      x: physics.body.x,
+      y: physics.body.z,      // z maps to legacy y
+      z: physics.body.z,
+      worldY: physics.body.y, // height
+    };
+
+    expect(snapshot.x).toBe(SANDBOX_SPAWN.x);
+    expect(snapshot.y).toBe(SANDBOX_SPAWN.z);
+    expect(snapshot.z).toBe(SANDBOX_SPAWN.z);
+    expect(snapshot.worldY).toBe(spawnHeight);
+  });
+});

package/template/apps/server/src/voxelChunkCache.ts

@@ -0,0 +1,31 @@
+import { generateVoxelChunk, type VoxelChunk, type VoxelTerrainOptions, type TerrainQueryFn } from '@loonylabs/gamedev-core';
+
+/**
+ * On-demand voxel chunk cache. Generates chunks deterministically
+ * from seed + options and caches them for repeated access.
+ *
+ * When terrainQueryFn is provided, it takes precedence over options
+ * and enables per-column biome-blended terrain generation.
+ */
+export class VoxelChunkCache {
+  private chunks = new Map<string, VoxelChunk>();
+
+  constructor(
+    private seed: number,
+    private options?: VoxelTerrainOptions,
+    private terrainQueryFn?: TerrainQueryFn,
+  ) {}
+
+  get(cx: number, cz: number): VoxelChunk {
+    const key = `${cx},${cz}`;
+    let chunk = this.chunks.get(key);
+    if (!chunk) {
+      chunk = generateVoxelChunk(cx, cz, this.seed, this.options ?? {}, this.terrainQueryFn);
+      this.chunks.set(key, chunk);
+    }
+    return chunk;
+  }
+
+  /** Compatible with getTerrainHeight's getChunk parameter. */
+  getChunkFn = (cx: number, cz: number): VoxelChunk | null => this.get(cx, cz);
+}

package/template/apps/server/src/voxelPlayerState.ts

@@ -0,0 +1,23 @@
+import { createPhysicsBody, createJumpState, type PhysicsBody, type JumpState } from '@loonylabs/gamedev-core';
+
+export interface VoxelPlayerPhysics {
+  body: PhysicsBody;
+  jumpState: JumpState;
+}
+
+/** Per-player physics state for voxel areas. Keyed by socketId. */
+export type VoxelPhysicsMap = Map<string, VoxelPlayerPhysics>;
+
+/** Create physics state for a player spawning at a given 3D position. */
+export function createVoxelPlayerPhysics(x: number, y: number, z: number): VoxelPlayerPhysics {
+  return {
+    body: createPhysicsBody(x, y, z),
+    jumpState: createJumpState(),
+  };
+}
+
+/**
+ * Global registry of voxel physics maps per area.
+ * The game loop registers its map here so message handlers can access it.
+ */
+export const voxelPhysicsRegistry = new Map<string, VoxelPhysicsMap>();

package/template/apps/server/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "sourceMap": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

package/template/apps/server/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['src/**/*.test.ts'],
+    testTimeout: 10000,
+  },
+});