@gnsx/genesys.sdk 4.2.9

package/src/templates/src/templates/sideScroller/src/game.ts

@@ -0,0 +1,121 @@
+
+import * as ENGINE from '@gnsx/genesys.js';
+import * as THREE from 'three';
+import './auto-imports.js';
+
+import { SideScrollerLevelGenerator } from './level-generator.js';
+import { SideScrollerPlayer } from './player.js';
+
+// ============================================================================
+// SIDE SCROLLER GAME
+// ============================================================================
+
+// A side-scroller game with animated character and infinite level generation
+class SideScrollerGame extends ENGINE.BaseGameLoop {
+  private player: SideScrollerPlayer | null = null;
+  private playerController: ENGINE.PlayerController | null = null;
+  private levelGenerator: SideScrollerLevelGenerator | null = null;
+
+  protected override createLoadingScreen(): ENGINE.ILoadingScreen | null {
+    // enable the default loading screen
+    return new ENGINE.DefaultLoadingScreen();
+  }
+
+  protected override async preStart(): Promise<void> {
+    this.createLevel();
+    this.createPlayer();
+  }
+
+  protected override tick(tickTime: ENGINE.TickTime): void {
+    super.tick(tickTime);
+
+    // Update level generation based on player position
+    if (this.player && this.levelGenerator) {
+      const playerPosition = this.player.getWorldPosition();
+      this.levelGenerator.updateLevel(playerPosition.x);
+    }
+  }
+
+  private createPlayer(): void {
+    const spawnX = 1;
+    // Create the side-scroller player with animated character
+    const position = new THREE.Vector3(spawnX, ENGINE.CHARACTER_HEIGHT / 2, 0);
+    this.player = SideScrollerPlayer.create({ position });
+
+    // Create the controller and possess the player
+    this.playerController = ENGINE.PlayerController.create();
+    this.playerController.possess(this.player);
+
+    // Add both to the world
+    this.world.addActors(this.player, this.playerController);
+    this.setInitialPlayerPosition(spawnX);
+  }
+
+  /**
+   * Sets the initial position of the player.
+   * @param spawnX - The X coordinate to spawn the player at.
+   */
+  private setInitialPlayerPosition(spawnX: number): void {
+    const groundHeight = this.findGroundHeightAtX(spawnX);
+    if (groundHeight !== null) {
+      this.player?.setWorldPosition(new THREE.Vector3(spawnX, groundHeight + ENGINE.CHARACTER_HEIGHT / 2, 0));
+    } else {
+      this.world.runInNextTick(() => {
+        this.setInitialPlayerPosition(spawnX);
+      });
+    }
+  }
+
+  /**
+   * Performs a hit test to find the ground height at a given X coordinate
+   * @param x - The X coordinate to test
+   * @returns The Y coordinate of the ground surface, or 0 if no ground is found
+   */
+  private findGroundHeightAtX(x: number): number | null {
+    // Start from a high position and cast downward
+    const rayOrigin = new THREE.Vector3(x, 50, 0);
+    const rayDirection = new THREE.Vector3(0, -1, 0); // Downward
+
+    const hitResults = this.world.getPhysicsEngine()?.performHitTest({
+      origin: rayOrigin,
+      direction: rayDirection,
+      maxDistance: 100, // Cast ray down 100 units
+      stopOnFirstHit: true,
+    });
+
+    if (hitResults && hitResults.length > 0) {
+      // Return the Y coordinate of the hit location (top surface of ground)
+      return hitResults[0].hitLocation.y;
+    }
+
+    return null;
+  }
+
+  private createLevel(): void {
+    // Create the level generator
+    this.levelGenerator = new SideScrollerLevelGenerator(this.world, {
+      enableDebugVisualization: false,
+      createGroundMesh: true
+    });
+
+    // Generate initial level chunks
+    this.levelGenerator.updateLevel(0);
+  }
+
+  public override destroy(): void {
+    // Clean up level generator
+    if (this.levelGenerator) {
+      this.levelGenerator.cleanup();
+      this.levelGenerator = null;
+    }
+    super.destroy();
+  }
+}
+
+export function main(container: HTMLElement, gameId: string): ENGINE.IGameLoop {
+  const game = new SideScrollerGame(container, {
+    ...ENGINE.BaseGameLoop.DEFAULT_OPTIONS,
+    gameId
+  });
+  return game;
+}

package/src/templates/src/templates/sideScroller/src/level-generator.ts

@@ -0,0 +1,361 @@
+import * as ENGINE from '@gnsx/genesys.js';
+import * as THREE from 'three';
+
+import { COLORS, LEVEL_CONFIG } from './const.js';
+
+// ============================================================================
+// LEVEL GENERATOR
+// ============================================================================
+
+// Interface for level generator configuration options
+interface LevelGeneratorOptions {
+  chunkSize?: number;
+  chunksAhead?: number;
+  chunksBehind?: number;
+  platformHeightRange?: { min: number; max: number };
+  platformWidthRange?: { min: number; max: number };
+  obstacleHeightRange?: { min: number; max: number };
+  chunkMargin?: number;
+  minSpacing?: number;
+  enableDebugVisualization?: boolean;
+  createGroundMesh?: boolean;
+}
+
+// Interface for tracking level chunks
+interface LevelChunk {
+  startX: number;
+  endX: number;
+  actors: ENGINE.Actor[];
+}
+
+// Interface for positioned elements within chunks
+interface PositionedElement {
+  x: number;
+  width: number;
+  height: number;
+  type: 'platform' | 'obstacle';
+}
+
+// Simple level generator for infinite side-scrolling levels
+export class SideScrollerLevelGenerator {
+  private world: ENGINE.World;
+  // Map of chunk index to chunk
+  private levelChunks: Map<number, LevelChunk> = new Map();
+
+  // Configuration
+  private chunkSize: number;
+  private chunksAhead: number;
+  private chunksBehind: number;
+  private platformHeightRange: { min: number; max: number };
+  private platformWidthRange: { min: number; max: number };
+  private obstacleHeightRange: { min: number; max: number };
+  private chunkMargin: number;
+  private minSpacing: number;
+  private debugVisualizationEnabled: boolean = false;
+  private createGroundMesh: boolean = false;
+
+  constructor(world: ENGINE.World, options: LevelGeneratorOptions = {}) {
+    this.world = world;
+
+    // Apply defaults
+    this.chunkSize = options.chunkSize ?? LEVEL_CONFIG.CHUNK_SIZE;
+    this.chunksAhead = options.chunksAhead ?? LEVEL_CONFIG.CHUNKS_AHEAD;
+    this.chunksBehind = options.chunksBehind ?? LEVEL_CONFIG.CHUNKS_BEHIND;
+    this.platformHeightRange = options.platformHeightRange ?? LEVEL_CONFIG.PLATFORM_HEIGHT_RANGE;
+    this.platformWidthRange = options.platformWidthRange ?? LEVEL_CONFIG.PLATFORM_WIDTH_RANGE;
+    this.obstacleHeightRange = options.obstacleHeightRange ?? LEVEL_CONFIG.OBSTACLE_HEIGHT_RANGE;
+    this.chunkMargin = options.chunkMargin ?? LEVEL_CONFIG.CHUNK_MARGIN;
+    this.minSpacing = options.minSpacing ?? LEVEL_CONFIG.MIN_SPACING;
+    this.debugVisualizationEnabled = options.enableDebugVisualization ?? false;
+    this.createGroundMesh = options.createGroundMesh ?? false;
+  }
+
+  public updateLevel(playerX: number): void {
+    const playerChunkIndex = this.getChunkIndex(playerX);
+
+    const validChunkIndices = [];
+    for (let i = playerChunkIndex - this.chunksBehind; i <= playerChunkIndex + this.chunksAhead; i++) {
+      this.generateChunk(i);
+      validChunkIndices.push(i);
+    }
+
+    for (const index of this.levelChunks.keys()) {
+      if (!validChunkIndices.includes(index)) {
+        this.removeChunk(index);
+      }
+    }
+  }
+
+  private getChunkIndex(x: number): number {
+    return Math.floor(x / this.chunkSize);
+  }
+
+  private removeChunk(index: number): void {
+    const chunk = this.levelChunks.get(index);
+    if (chunk) {
+      this.world.removeActors(...chunk.actors);
+      this.levelChunks.delete(index);
+      console.log(`[LevelGenerator] Removed chunk at index ${index}`);
+    }
+  }
+
+  private generateChunk(index: number): void {
+    if (this.levelChunks.has(index)) {
+      return;
+    }
+
+    const startX = index * this.chunkSize;
+    const endX = startX + this.chunkSize;
+    const actors: ENGINE.Actor[] = [];
+
+    // Generate positioned elements for this chunk
+    const elements = this.generatePositionedElements(startX);
+
+    // Create actors for each element
+    for (const element of elements) {
+      const actor = this.createElementActor(element);
+      actors.push(actor);
+    }
+
+    // Add ground mesh if enabled
+    if (this.createGroundMesh) {
+      const groundActor = this.createGroundMeshActor(startX);
+      actors.push(groundActor);
+    }
+
+    // Add debug visualization if enabled
+    if (this.debugVisualizationEnabled) {
+      const debugActor = this.createChunkDebugVisualization(startX);
+      actors.push(debugActor);
+    }
+
+    // Add all actors to the world
+    this.world.addActors(...actors);
+
+    // Track this chunk
+    const chunk: LevelChunk = {
+      startX,
+      endX,
+      actors,
+    };
+    console.log(`[LevelGenerator] Generated chunk at index ${index}`);
+    this.levelChunks.set(index, chunk);
+  }
+
+  private generatePositionedElements(startX: number): PositionedElement[] {
+    const elements: PositionedElement[] = [];
+    const usableWidth = this.chunkSize - (this.chunkMargin * 2); // Leave margin on each side
+    const usableStartX = startX + this.chunkMargin;
+
+    // Simple alternating generation: platform -> obstacle -> platform -> obstacle...
+    const totalElements = Math.floor(usableWidth / this.minSpacing); // How many elements can fit
+
+    let currentX = usableStartX;
+    let isPlatform = true; // Start with platform
+
+    for (let i = 0; i < totalElements && currentX < (startX + this.chunkSize - this.chunkMargin); i++) {
+      if (isPlatform) {
+        // Generate platform with random dimensions
+        const width = this.platformWidthRange.min +
+          Math.random() * (this.platformWidthRange.max - this.platformWidthRange.min);
+        const height = this.platformHeightRange.min +
+          Math.random() * (this.platformHeightRange.max - this.platformHeightRange.min);
+
+        elements.push({
+          x: currentX + width / 2, // Center position
+          width: width,
+          height: height,
+          type: 'platform'
+        });
+
+        currentX += width + this.minSpacing; // Move past this platform plus spacing
+
+      } else {
+        // Generate obstacle with random dimensions
+        const width = LEVEL_CONFIG.OBSTACLE_WIDTH_RANGE.min +
+          Math.random() * (LEVEL_CONFIG.OBSTACLE_WIDTH_RANGE.max - LEVEL_CONFIG.OBSTACLE_WIDTH_RANGE.min);
+        const height = this.obstacleHeightRange.min +
+          Math.random() * (this.obstacleHeightRange.max - this.obstacleHeightRange.min);
+
+        elements.push({
+          x: currentX + width / 2, // Center position
+          width: width,
+          height: height,
+          type: 'obstacle'
+        });
+
+        currentX += width + this.minSpacing; // Move past this obstacle plus spacing
+      }
+
+      // Alternate between platform and obstacle
+      isPlatform = !isPlatform;
+    }
+
+    return elements;
+  }
+
+  private createElementActor(element: PositionedElement): ENGINE.Actor {
+    const geometry = new THREE.BoxGeometry(element.width, element.height, LEVEL_CONFIG.DEPTH);
+    const material = new THREE.MeshStandardMaterial({ color: element.type === 'platform' ? COLORS.PLATFORM : COLORS.OBSTACLE });
+
+    const meshComponent = ENGINE.MeshComponent.create({
+      geometry: geometry,
+      material: material,
+      position: new THREE.Vector3(element.x, element.height / 2, 0), // Position at ground level
+      physicsOptions: {
+        enabled: true,
+        motionType: ENGINE.PhysicsMotionType.Static,
+        collisionProfile: ENGINE.DefaultCollisionProfile.BlockAll,
+      },
+    });
+
+    // Enable shadow casting and receiving
+    meshComponent.castShadow = true;
+    meshComponent.receiveShadow = true;
+
+    const actor = ENGINE.Actor.create();
+    actor.setRootComponent(meshComponent, false);
+    return actor;
+  }
+
+  private createChunkDebugVisualization(startX: number): ENGINE.Actor {
+    // Create a wireframe box to visualize chunk boundaries
+    const chunkGeometry = new THREE.BoxGeometry(
+      this.chunkSize,
+      LEVEL_CONFIG.DEBUG_VISUALIZATION_HEIGHT,
+      LEVEL_CONFIG.DEPTH
+    );
+
+    const chunkMaterial = new THREE.MeshBasicMaterial({
+      color: LEVEL_CONFIG.DEBUG_VISUALIZATION_COLOR,
+      opacity: LEVEL_CONFIG.DEBUG_VISUALIZATION_OPACITY,
+      wireframe: true,
+      transparent: true,
+    });
+
+    const meshComponent = ENGINE.MeshComponent.create({
+      geometry: chunkGeometry,
+      material: chunkMaterial,
+      position: new THREE.Vector3(
+        startX + this.chunkSize / 2,
+        LEVEL_CONFIG.DEBUG_VISUALIZATION_HEIGHT / 2,
+        0
+      ),
+      physicsOptions: {
+        enabled: false,
+      },
+    });
+
+    const chunkBoundary = ENGINE.Actor.create();
+    chunkBoundary.setRootComponent(meshComponent, false);
+    return chunkBoundary;
+  }
+
+  private createGroundMeshActor(startX: number): ENGINE.Actor {
+    // Create a ground mesh that spans the entire chunk width
+    const groundGeometry = new THREE.BoxGeometry(
+      this.chunkSize,
+      LEVEL_CONFIG.GROUND_HEIGHT,
+      LEVEL_CONFIG.DEPTH
+    );
+
+    const groundMaterial = new THREE.MeshStandardMaterial({
+      color: COLORS.GROUND,
+    });
+
+    const groundMeshComponent = ENGINE.MeshComponent.create({
+      geometry: groundGeometry,
+      material: groundMaterial,
+      position: new THREE.Vector3(
+        startX + this.chunkSize / 2,
+        LEVEL_CONFIG.GROUND_Y_POSITION,
+        0
+      ),
+      physicsOptions: {
+        enabled: true,
+        motionType: ENGINE.PhysicsMotionType.Static,
+        collisionProfile: ENGINE.DefaultCollisionProfile.BlockAll,
+      },
+    });
+
+    // Enable shadow receiving
+    groundMeshComponent.receiveShadow = true;
+
+    const actor = ENGINE.Actor.create();
+    actor.setRootComponent(groundMeshComponent, false);
+    return actor;
+  }
+
+  /**
+   * Gets detailed geometry information at a given x location.
+   * @param x - The x coordinate to query
+   * @returns An array of geometry info objects at the given x location
+   */
+  public getGeometryInfoAtX(x: number): Array<{
+    type: 'ground' | 'platform' | 'obstacle';
+    topY: number;
+    bottomY: number;
+    width: number;
+    centerX: number;
+  }> {
+    const chunkIndex = this.getChunkIndex(x);
+    const chunk = this.levelChunks.get(chunkIndex);
+
+    if (!chunk) {
+      return [];
+    }
+
+    const geometries: Array<{
+      type: 'ground' | 'platform' | 'obstacle';
+      topY: number;
+      bottomY: number;
+      width: number;
+      centerX: number;
+    }> = [];
+
+    // Add ground mesh if enabled
+    if (this.createGroundMesh) {
+      const groundCenterY = LEVEL_CONFIG.GROUND_Y_POSITION;
+      const groundHalfHeight = LEVEL_CONFIG.GROUND_HEIGHT / 2;
+      geometries.push({
+        type: 'ground',
+        topY: groundCenterY + groundHalfHeight,
+        bottomY: groundCenterY - groundHalfHeight,
+        width: this.chunkSize,
+        centerX: chunk.startX + this.chunkSize / 2
+      });
+    }
+
+    // Add positioned elements (platforms and obstacles)
+    const elements = this.generatePositionedElements(chunk.startX);
+
+    for (const element of elements) {
+      const elementLeft = element.x - element.width / 2;
+      const elementRight = element.x + element.width / 2;
+
+      // Check if the x coordinate falls within this element's bounds
+      if (x >= elementLeft && x <= elementRight) {
+        geometries.push({
+          type: element.type,
+          topY: element.height,
+          bottomY: 0, // Elements are positioned at ground level (y=0 bottom)
+          width: element.width,
+          centerX: element.x
+        });
+      }
+    }
+
+    // Sort by top height (highest first)
+    geometries.sort((a, b) => b.topY - a.topY);
+
+    return geometries;
+  }
+
+  public cleanup(): void {
+    for (const index of this.levelChunks.keys()) {
+      this.removeChunk(index);
+    }
+    this.levelChunks.clear();
+    console.log('[LevelGenerator] Cleaned up');
+  }
+}

package/src/templates/src/templates/sideScroller/src/player.ts

@@ -0,0 +1,123 @@
+import * as ENGINE from '@gnsx/genesys.js';
+import * as THREE from 'three';
+
+import { CAMERA_SETTINGS, PLAYER_MOVEMENT } from './const.js';
+
+// ============================================================================
+// PLAYER PAWN
+// ============================================================================
+
+// The side-scroller player pawn class using animated character.
+@ENGINE.GameClass()
+export class SideScrollerPlayer extends ENGINE.ThirdPersonCharacterPawn {
+  camera: THREE.PerspectiveCamera;
+  characterMesh: ENGINE.GLTFMeshComponent | null = null;
+  smoothedCameraHeight: number | null = null;
+  smoothedLookAtHeight: number | null = null;
+
+  constructor() {
+    super();
+    // Create directional movement component for side-scrolling
+    const movementComponent = ENGINE.DirectionalCharacterMovementComponent.create({
+      direction: ENGINE.CharacterMovementDirection.LeftRight, // Move left and right
+      autoMove: false, // Player controls movement manually
+      jumpSpeed: PLAYER_MOVEMENT.JUMP_SPEED,
+      maxSpeed: PLAYER_MOVEMENT.MAX_SPEED,
+      maxMidAirJumps: PLAYER_MOVEMENT.MAX_MID_AIR_JUMPS, // Allow double jump
+      // Physics and movement settings for platformer feel
+      accelerationLambda: PLAYER_MOVEMENT.ACCELERATION_LAMBDA,
+      decelerationLambda: PLAYER_MOVEMENT.DECELERATION_LAMBDA,
+      midAirAccelerationLambda: PLAYER_MOVEMENT.MID_AIR_ACCELERATION_LAMBDA,
+      midAirDecelerationLambda: PLAYER_MOVEMENT.MID_AIR_DECELERATION_LAMBDA,
+    });
+
+    // Physics options for the player
+    const physicsOptions: ENGINE.ComponentPhysicsOptions = {
+      enabled: true,
+      motionType: ENGINE.PhysicsMotionType.KinematicVelocityBased,
+      collisionProfile: ENGINE.DefaultCollisionProfile.Character,
+      generateCollisionEvents: true,
+    };
+
+    // Create root component with physics (invisible capsule for collision)
+    const rootComponent = ENGINE.MeshComponent.create({
+      geometry: new THREE.CapsuleGeometry(
+        ENGINE.CHARACTER_WIDTH / 2,
+        ENGINE.CHARACTER_HEIGHT - ENGINE.CHARACTER_WIDTH
+      ),
+      material: new THREE.MeshStandardMaterial({
+        color: 0xffff00,
+        visible: false, // Make invisible since we'll have the animated character mesh
+        transparent: true,
+        opacity: 0.5
+      }),
+      physicsOptions,
+    });
+
+    this.setRootComponent(rootComponent, true);
+    this.movementComponent = movementComponent;
+
+    // Use default character model from engine assets
+    this.configUrl = '@engine/assets/character/config/mannequin-anim.json';
+
+    this.meshComponent.position.copy(new THREE.Vector3(0, -ENGINE.CHARACTER_HEIGHT / 2, 0));
+    this.meshComponent.rotation.copy(new THREE.Euler(0, Math.PI, 0)); // Face right initially
+    rootComponent.add(this.meshComponent);
+
+    // Enable shadow casting for the character
+    this.rootComponent.castShadow = true;
+    this.camera = new THREE.PerspectiveCamera(CAMERA_SETTINGS.FOV, 1, CAMERA_SETTINGS.NEAR, CAMERA_SETTINGS.FAR);
+
+    this.enableDirectionalLightFollowing = true;
+  }
+
+  public override doBeginPlay(): void {
+    super.doBeginPlay();
+    this.getWorld()?.setOverrideCamera(this.camera);
+  }
+
+  public override tickPrePhysics(deltaTime: number): void {
+    super.tickPrePhysics(deltaTime);
+
+    // manually update the camera position
+    const desiredCameraPosition = this.rootComponent.localToWorld(new THREE.Vector3(
+      CAMERA_SETTINGS.POSITION.x,
+      CAMERA_SETTINGS.POSITION.y,
+      CAMERA_SETTINGS.POSITION.z
+    ));
+    const desiredCameraLookAt = this.rootComponent.localToWorld(new THREE.Vector3(
+      CAMERA_SETTINGS.LOOK_AT.x,
+      CAMERA_SETTINGS.LOOK_AT.y,
+      CAMERA_SETTINGS.LOOK_AT.z
+    ));
+    this.smoothedCameraHeight ??= desiredCameraPosition.y;
+    this.smoothedLookAtHeight ??= desiredCameraLookAt.y;
+
+    this.smoothedCameraHeight = THREE.MathUtils.damp(this.smoothedCameraHeight, desiredCameraPosition.y, CAMERA_SETTINGS.DAMP_FACTOR, deltaTime);
+    this.smoothedLookAtHeight = THREE.MathUtils.damp(this.smoothedLookAtHeight, desiredCameraLookAt.y, CAMERA_SETTINGS.DAMP_FACTOR, deltaTime);
+
+    this.camera.position.x = desiredCameraPosition.x;
+    this.camera.position.y = this.smoothedCameraHeight;
+    this.camera.position.z = desiredCameraPosition.z;
+
+    this.camera.lookAt(new THREE.Vector3(
+      desiredCameraLookAt.x,
+      this.smoothedLookAtHeight,
+      desiredCameraLookAt.z
+    ));
+
+    // change the direction of the character mesh based on the movement direction
+    this.characterMesh ??= this.getComponent(ENGINE.GLTFMeshComponent);
+    if (this.characterMesh && this.movementComponent) {
+      const movementComponent = this.movementComponent as ENGINE.DirectionalCharacterMovementComponent;
+      const velocity = movementComponent.getVelocities();
+      if (velocity.right > 0.1) {
+        // Moving right - face right (90 degrees)
+        this.characterMesh.rotation.set(0, Math.PI / 2, 0);
+      } else if (velocity.right < -0.1) {
+        // Moving left - face left (-90 degrees)
+        this.characterMesh.rotation.set(0, -Math.PI / 2, 0);
+      }
+    }
+  }
+}