@gnsx/genesys.sdk 4.2.9

package/src/templates/src/templates/vehicle/src/mesh-vehicle.ts

@@ -0,0 +1,189 @@
+import * as ENGINE from '@gnsx/genesys.js';
+import * as THREE from 'three';
+
+import { BaseVehicle } from './base-vehicle.js';
+
+/**
+ * A vehicle that uses a 3D mesh model for visual representation
+ *
+ * Key points:
+ * - Uses invisible collision box for physics simulation (separate from visual mesh)
+ * - Loads GLB model for visual representation via GLTFMeshComponent
+ * - Movement parameters configured in createVehicleMovementComponent
+ * - No component is persisted (root is transient) in order to support recreating all the components in code (which is desired)
+ * - Do not create the builtin wheel mesh since the GLB models are used instead (createWheelMeshes = false)
+ * - Visual mesh is positioned and scaled to match collision box
+ * - Wheel mesh transforms are updated using the onWheelUpdated delegate
+ *
+ */
+@ENGINE.GameClass()
+export class MeshVehicle extends BaseVehicle {
+  constructor() {
+    super();
+    // the root component is only used for collision and physics simulation
+    const rootComponent = ENGINE.MeshComponent.create({
+      geometry: new THREE.BoxGeometry(2.77, 1.79, 5.75),
+      material: new THREE.MeshStandardMaterial({
+        color: 0x4444FF,
+        roughness: 0.7,
+        metalness: 0.3,
+        visible: false,
+        transparent: true,
+        opacity: 0.5,
+      }),
+      physicsOptions: {
+        enabled: true,
+        motionType: ENGINE.PhysicsMotionType.Dynamic,
+        generateCollisionEvents: true,
+      },
+    });
+    rootComponent.name = 'root';
+    this.setRootComponent(rootComponent, true);
+    // mark the component as transient, this prevents all the components from being saved since we're recreating them in code
+    rootComponent.setTransient(true);
+
+    const chassisComponent = ENGINE.GLTFMeshComponent.create({
+      modelUrl: '@project/assets/models/cyberTruck/chassis.glb',
+      position: new THREE.Vector3(0, 0, -0.75),
+      material: new THREE.MeshStandardMaterial({
+        color: 0x4444FF,
+        roughness: 0.7,
+        metalness: 0.3,
+      }),
+      physicsOptions: {
+        enabled: false,
+      }
+    });
+    chassisComponent.castShadow = true;
+    chassisComponent.name = 'chassis';
+    rootComponent.add(chassisComponent);
+
+    const wheelMeshes: ENGINE.GLTFMeshComponent[] = [];
+    for (let i = 0; i < 4; i++) {
+      const wheelComponent = ENGINE.GLTFMeshComponent.create({
+        modelUrl: '@project/assets/models/cyberTruck/wheel.glb',
+        material: new THREE.MeshStandardMaterial({
+          color: 0x44FF44,
+          roughness: 0.7,
+          metalness: 0.3,
+        }),
+        physicsOptions: {
+          enabled: false,
+        }
+      });
+      wheelComponent.castShadow = true;
+      wheelComponent.name = `wheel_${i}`;
+      wheelMeshes.push(wheelComponent);
+    }
+    rootComponent.add(...wheelMeshes);
+    const vehicleMovementComponent = MeshVehicle.createVehicleMovementComponent();
+
+    this.movementComponent = vehicleMovementComponent;
+
+    const wheelComponents = this.getComponents(ENGINE.GLTFMeshComponent).filter(component => component.name.startsWith('wheel_'));
+
+    vehicleMovementComponent.onWheelUpdated.add((component, wheelIndex, wheelState) => {
+      // The first mesh component is the chassis component, so we need to skip it
+      const wheelMesh = wheelComponents[wheelIndex];
+
+      // Apply the final transformation to the wheel mesh
+      wheelMesh.position.copy(wheelState.relativePosition);
+      wheelMesh.quaternion.copy(wheelState.relativeQuaternion);
+
+      // Apply additional 180-degree rotation around Y-axis for wheels 0 and 2
+      if (wheelIndex === 0 || wheelIndex === 2) {
+        const yRotation = new THREE.Quaternion();
+        yRotation.setFromAxisAngle(new THREE.Vector3(0, 1, 0), Math.PI);
+        wheelMesh.quaternion.multiplyQuaternions(wheelMesh.quaternion, yRotation);
+      }
+    });
+  }
+
+  static createVehicleMovementComponent(): ENGINE.VehicleMovementComponent {
+    const wheelBaseWidth = 3.2;
+    const wheelBaseLength = 3.8;
+    const wheelBaseHeight = -0.5;
+    const wheelRadius = 0.55;
+    const suspensionRestLength = 0.8;
+    const wheelWidth = 0.53;
+    const suspensionStiffness = 20;
+    const suspensionCompression = 1.83;
+    const suspensionRelaxation = 1.88;
+    const sideFrictionStiffness = 2;
+    const frictionSlip = 50;
+
+    // Create vehicle movement component
+    const vehicleMovement = ENGINE.VehicleMovementComponent.create({
+      createWheelMeshes: false,
+      maxEnginePower: 100,
+      maxBrakeForce: 1.5,
+      maxSteeringAngle: Math.PI / 6, // 30 degrees
+      engineResponseRate: 8.0,
+      steeringResponseRate: 12.0,
+      brakeResponseRate: 15.0,
+      wheelMaterialColor: 0x333333,
+      autoBreakWhenNotPossessed: 1,
+      autoStopBreak: 1,
+      wheels: [
+      // Default 4-wheel configuration
+        {
+          position: new THREE.Vector3(-wheelBaseWidth / 2, wheelBaseHeight, -wheelBaseLength / 2), // Front left
+          radius: wheelRadius,
+          width: wheelWidth,
+          canSteer: true,
+          isPowered: false,
+          canBrake: true,
+          suspensionRestLength,
+          suspensionStiffness,
+          suspensionCompression,
+          suspensionRelaxation,
+          sideFrictionStiffness,
+          frictionSlip,
+        },
+        {
+          position: new THREE.Vector3(wheelBaseWidth / 2, wheelBaseHeight, -wheelBaseLength / 2), // Front right
+          radius: wheelRadius,
+          width: wheelWidth,
+          canSteer: true,
+          isPowered: false,
+          canBrake: true,
+          suspensionRestLength,
+          suspensionStiffness,
+          suspensionCompression,
+          suspensionRelaxation,
+          sideFrictionStiffness,
+          frictionSlip,
+        },
+        {
+          position: new THREE.Vector3(-wheelBaseWidth / 2, wheelBaseHeight, wheelBaseLength / 2), // Rear left
+          radius: wheelRadius,
+          width: wheelWidth,
+          canSteer: false,
+          isPowered: true,
+          canBrake: true,
+          suspensionRestLength,
+          suspensionStiffness,
+          suspensionCompression,
+          suspensionRelaxation,
+          sideFrictionStiffness,
+          frictionSlip,
+        },
+        {
+          position: new THREE.Vector3(wheelBaseWidth / 2, wheelBaseHeight, wheelBaseLength / 2), // Rear right
+          radius: wheelRadius,
+          width: wheelWidth,
+          canSteer: false,
+          isPowered: true,
+          canBrake: true,
+          suspensionRestLength,
+          suspensionStiffness,
+          suspensionCompression,
+          suspensionRelaxation,
+          sideFrictionStiffness,
+          frictionSlip,
+        },
+      ],
+    });
+    return vehicleMovement;
+  }
+}

package/src/templates/src/templates/vehicle/src/player.ts

@@ -0,0 +1,106 @@
+import * as ENGINE from '@gnsx/genesys.js';
+import * as THREE from 'three';
+
+import { BaseVehicle } from './base-vehicle.js';
+
+
+/**
+ * A vehicle player class.
+ *
+ * Key points:
+ * - No need to provide movementComponent and camera, they are created internally
+ * - The pawn is set to be transient so it's never saved in the level
+ * - The directional light follows the player for consistent shadows
+ *
+ */
+@ENGINE.GameClass()
+export class VehiclePlayer extends ENGINE.ThirdPersonCharacterPawn {
+  // Omit all the options that are created internally
+  constructor() {
+    super();
+    // simple camera component - contains a perspective camera by default
+    const camera = new THREE.PerspectiveCamera(ENGINE.CAMERA_FOV, 1, 0.1, 1000);
+    // set camera position for third person view
+    camera.position.set(0, ENGINE.CHARACTER_HEIGHT * 1.3, ENGINE.CHARACTER_HEIGHT * 2);
+    camera.lookAt(0, 0, 0);
+
+    // use capsule root component for collision
+    const rootComponent = ENGINE.MeshComponent.create({
+      geometry: ENGINE.GameBuilder.createDefaultPawnCapsuleGeometry(),
+      material: new THREE.MeshStandardMaterial({ color: ENGINE.Color.YELLOW, visible: false, transparent: true, opacity: 0.5 }),
+      physicsOptions: {
+        enabled: true,
+        // KinematicVelocityBased is required to use the physics character controller
+        motionType: ENGINE.PhysicsMotionType.KinematicVelocityBased,
+        collisionProfile: ENGINE.DefaultCollisionProfile.Character,
+      },
+    });
+
+    this.setRootComponent(rootComponent, true);
+    this.rootComponent.add(camera);
+
+    // use third person movement mechanics
+    const movementComponent = ENGINE.CharacterMovementComponent.create({
+      movementType: ENGINE.CharacterMovementType.ThirdPerson,
+    });
+
+    this.movementComponent = movementComponent;
+
+    // Character model settings
+    this.enableDirectionalLightFollowing = true;
+    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));
+    rootComponent.add(this.meshComponent);
+
+    // set the pawn to be transient so it's never saved in the level
+    this.setTransient(true);
+  }
+
+  protected override doBeginPlay(): void {
+    super.doBeginPlay();
+    this.setupVehicleInteraction();
+  }
+
+  protected setupVehicleInteraction(): void {
+    // Add E key input handler for vehicle possession
+    this.onKeyDown.add((e: KeyboardEvent) => {
+      if (e.key.toLowerCase() === 'e') {
+        this.tryEnterVehicle();
+        return true;
+      }
+      return false;
+    });
+  }
+
+  protected tryEnterVehicle(): void {
+    // Find nearby vehicles that can be entered
+    const vehicles = this.world!.getActors(BaseVehicle);
+
+    for (const vehicle of vehicles) {
+      if (vehicle.canBeEntered() && vehicle.getNearbyPlayer() === this) {
+        this.enterVehicle(vehicle);
+        break;
+      }
+    }
+  }
+
+  protected enterVehicle(vehicle: BaseVehicle): void {
+    // Get the current player controller
+    const controller = this.getPlayerController();
+
+    if (controller) {
+      // Set this player as the entered player in the vehicle
+      vehicle.setEnteredPlayer(this);
+
+      // Unpossess current pawn and possess the vehicle
+      controller.unpossess();
+      controller.possess(vehicle);
+
+      // Hide the player character
+      this.rootComponent.visible = false;
+      this.rootComponent.setPhysicsEnabled(false);
+    }
+  }
+}

package/src/templates/src/templates/vehicle/src/primitive-vehicle.ts

@@ -0,0 +1,264 @@
+import * as ENGINE from '@gnsx/genesys.js';
+import * as THREE from 'three';
+
+import { BaseVehicle } from './base-vehicle.js';
+
+
+/**
+ * A simple vehicle with a box geometry
+ *
+ * Key points:
+ * - Movement parameters configured in createVehicleMovementComponent
+ * - No component is persisted (root is transient) in order to support recreating all the components in code (which is desired)
+ * - Rely on the builtin feature to create the wheel mesh (createWheelMeshes = true), no need to create them manually
+ * - All decorative meshes have physics disabled won't mess with the handling
+ * - Find the tail light meshes after the constructor so it works with deserialized actor
+ * - Rely on the base vehicle class to handle the camera and player interaction
+ */
+@ENGINE.GameClass()
+export class PrimitiveVehicle extends BaseVehicle {
+  private tailLightComponents: ENGINE.MeshComponent[] = [];
+
+  constructor() {
+    super();
+
+    // Create chassis mesh
+    const rootComponent = ENGINE.MeshComponent.create({
+      geometry: new THREE.BoxGeometry(2, 1, 4),
+      material: new THREE.MeshStandardMaterial({
+        color: 0x4444FF,
+        roughness: 0.7,
+        metalness: 0.3,
+      }),
+      physicsOptions: {
+        enabled: true,
+        motionType: ENGINE.PhysicsMotionType.Dynamic,
+        generateCollisionEvents: true,
+      },
+    });
+    rootComponent.castShadow = true;
+    rootComponent.name = 'chassis';
+    // mark the component as transient, this prevents all the components from being saved since we're recreating them in code
+    rootComponent.setTransient(true);
+    this.setRootComponent(rootComponent, true);
+    // create decorative meshes
+    PrimitiveVehicle.createDecorativeMeshes(rootComponent);
+    this.movementComponent = PrimitiveVehicle.createVehicleMovementComponent();
+
+    this.tailLightComponents = this.getComponents(ENGINE.MeshComponent)
+      .filter((component) => component.name.includes('_taillight'));
+  }
+
+  public override tickPrePhysics(deltaTime: number): void {
+    super.tickPrePhysics(deltaTime);
+    this.updateBrakeLights();
+  }
+
+  private updateBrakeLights(): void {
+    if (!this.movementComponent || this.tailLightComponents.length === 0) return;
+
+    const inputState = this.movementComponent.getInputState() as ENGINE.VehicleMovementInputState;
+    const isBraking = inputState.brakeInput > 0;
+
+    for (const tailLightComponent of this.tailLightComponents) {
+      const mesh = tailLightComponent.getMesh();
+      if (mesh && mesh.material) {
+        const material = mesh.material as THREE.MeshStandardMaterial;
+        if (isBraking) {
+          material.color.setHex(0xFF0000);
+        } else {
+          material.color.setHex(0xFFFFFF);
+        }
+      }
+    }
+  }
+
+  static createDecorativeMeshes(rootComponent: ENGINE.MeshComponent): void {
+    // Add windshield
+    const windshieldComponent = ENGINE.MeshComponent.create({
+      geometry: new THREE.BoxGeometry(1.8, 1.8, 0.1),
+      material: new THREE.MeshStandardMaterial({
+        color: 0x87CEEB,
+        transparent: true,
+        opacity: 0.5,
+        roughness: 0.1,
+        metalness: 0.1,
+      }),
+      physicsOptions: {
+        enabled: false,
+      }
+    });
+    windshieldComponent.position.set(0, 0.4, -1.5);
+    windshieldComponent.rotation.x = Math.PI / 8; // Slight tilt
+    windshieldComponent.name = 'windshield';
+    rootComponent.add(windshieldComponent);
+
+    // Add left headlight
+    const leftHeadlightComponent = ENGINE.MeshComponent.create({
+      geometry: new THREE.CylinderGeometry(0.15, 0.15, 0.1, 8),
+      material: new THREE.MeshStandardMaterial({
+        color: 0xFFFFFF,
+        emissive: 0xFFFFAA,
+        emissiveIntensity: 0.3,
+      }),
+      physicsOptions: {
+        enabled: false,
+      }
+    });
+    leftHeadlightComponent.position.set(-0.7, 0.1, -2.05);
+    leftHeadlightComponent.rotation.z = Math.PI / 2;
+    leftHeadlightComponent.name = 'left_headlight';
+    rootComponent.add(leftHeadlightComponent);
+
+    // Add right headlight
+    const rightHeadlightComponent = ENGINE.MeshComponent.create({
+      geometry: new THREE.CylinderGeometry(0.15, 0.15, 0.1, 8),
+      material: new THREE.MeshStandardMaterial({
+        color: 0xFFFFFF,
+        emissive: 0xFFFFAA,
+        emissiveIntensity: 0.3,
+      }),
+      physicsOptions: {
+        enabled: false,
+      }
+    });
+    rightHeadlightComponent.position.set(0.7, 0.1, -2.05);
+    rightHeadlightComponent.rotation.z = Math.PI / 2;
+    rightHeadlightComponent.name = 'right_headlight';
+    rootComponent.add(rightHeadlightComponent);
+
+    // Add left tail light
+    const leftTaillightMaterial = new THREE.MeshStandardMaterial({
+      color: 0xFF0000,
+      emissive: 0x440000,
+      emissiveIntensity: 0.2,
+    });
+    const leftTaillightComponent = ENGINE.MeshComponent.create({
+      geometry: new THREE.CylinderGeometry(0.1, 0.1, 0.1, 8),
+      material: leftTaillightMaterial,
+      physicsOptions: {
+        enabled: false,
+      }
+    });
+    leftTaillightComponent.position.set(-0.7, 0.1, 2.05);
+    leftTaillightComponent.rotation.z = Math.PI / 2;
+    leftTaillightComponent.name = 'left_taillight';
+    rootComponent.add(leftTaillightComponent);
+
+    // Add right tail light
+    const rightTaillightMaterial = new THREE.MeshStandardMaterial({
+      color: 0xFF0000,
+      emissive: 0x440000,
+      emissiveIntensity: 0.2,
+    });
+    const rightTaillightComponent = ENGINE.MeshComponent.create({
+      geometry: new THREE.CylinderGeometry(0.1, 0.1, 0.1, 8),
+      material: rightTaillightMaterial,
+      physicsOptions: {
+        enabled: false,
+      }
+    });
+    rightTaillightComponent.position.set(0.7, 0.1, 2.05);
+    rightTaillightComponent.rotation.z = Math.PI / 2;
+    rightTaillightComponent.name = 'right_taillight';
+    rootComponent.add(rightTaillightComponent);
+  }
+
+  static createVehicleMovementComponent(): ENGINE.VehicleMovementComponent {
+    const wheelBaseWidth = 2.6;
+    const wheelBaseLength = 3.0;
+    const wheelBaseHeight = 0;
+    const suspensionRestLength = 0.6;
+    const wheelRadius = 0.5;
+    const wheelWidth = 0.4;
+    const suspensionStiffness = 20;
+    const suspensionCompression = 0.83;
+    const suspensionRelaxation = 0.88;
+    const maxSuspensionForce = 6000.0;
+    const maxSuspensionTravel = 5.0;
+    const sideFrictionStiffness = 2;
+    const frictionSlip = 8;
+
+    const options = {
+      maxEnginePower: 35,
+      maxSteeringAngle: Math.PI / 6, // 30 degrees
+      maxBrakeForce: 1,
+      engineResponseRate: 8.0,
+      steeringResponseRate: 12.0,
+      brakeResponseRate: 15.0,
+      createWheelMeshes: true,
+      wheelMaterialColor: 0x333333,
+      autoBreakWhenNotPossessed: 1,
+      autoStopBreak: 0.5,
+      wheels: [
+        // Default 4-wheel configuration
+        {
+          position: new THREE.Vector3(-wheelBaseWidth / 2, wheelBaseHeight, -wheelBaseLength / 2), // Front left
+          radius: wheelRadius,
+          width: wheelWidth,
+          canSteer: true,
+          isPowered: false,
+          canBrake: true,
+          suspensionRestLength,
+          suspensionStiffness,
+          suspensionCompression,
+          suspensionRelaxation,
+          maxSuspensionForce,
+          maxSuspensionTravel,
+          sideFrictionStiffness,
+          frictionSlip,
+        },
+        {
+          position: new THREE.Vector3(wheelBaseWidth / 2, wheelBaseHeight, -wheelBaseLength / 2), // Front right
+          radius: wheelRadius,
+          width: wheelWidth,
+          canSteer: true,
+          isPowered: false,
+          canBrake: true,
+          suspensionRestLength,
+          suspensionStiffness,
+          suspensionCompression,
+          suspensionRelaxation,
+          maxSuspensionForce,
+          maxSuspensionTravel,
+          sideFrictionStiffness,
+          frictionSlip,
+        },
+        {
+          position: new THREE.Vector3(-wheelBaseWidth / 2, wheelBaseHeight, wheelBaseLength / 2), // Rear left
+          radius: wheelRadius,
+          width: wheelWidth,
+          canSteer: false,
+          isPowered: true,
+          canBrake: true,
+          suspensionRestLength,
+          suspensionStiffness,
+          suspensionCompression,
+          suspensionRelaxation,
+          maxSuspensionForce,
+          maxSuspensionTravel,
+          sideFrictionStiffness,
+          frictionSlip,
+        },
+        {
+          position: new THREE.Vector3(wheelBaseWidth / 2, wheelBaseHeight, wheelBaseLength / 2), // Rear right
+          radius: wheelRadius,
+          width: wheelWidth,
+          canSteer: false,
+          isPowered: true,
+          canBrake: true,
+          suspensionRestLength,
+          suspensionStiffness,
+          suspensionCompression,
+          suspensionRelaxation,
+          maxSuspensionForce,
+          maxSuspensionTravel,
+          sideFrictionStiffness,
+          frictionSlip,
+        },
+      ],
+    };
+
+    return ENGINE.VehicleMovementComponent.create(options);
+  }
+}

package/src/templates/src/templates/vehicle/src/ui-hints.ts

@@ -0,0 +1,101 @@
+import * as ENGINE from '@gnsx/genesys.js';
+
+/**
+ * Dismissable UI component that displays control hints when the game starts
+ */
+@ENGINE.GameClass()
+export class UIHints extends ENGINE.Actor {
+  private uiElement: ENGINE.UIElement | null = null;
+
+  constructor() {
+    super();
+    this.setTransient(true); // Don't save this UI element to the level
+  }
+
+  protected override doBeginPlay(): void {
+    super.doBeginPlay();
+    this.createHUD();
+  }
+
+  protected override doEndPlay(): void {
+    this.removeHUD();
+    super.doEndPlay();
+  }
+
+  private createHUD(): void {
+    const uiManager = this.world!.uiManager;
+
+    // Create the UI element using the engine's UI system
+    this.uiElement = uiManager.createElement('game-hints', {
+      style: {
+        position: 'absolute',
+        top: '50px',
+        right: '50px',
+        background: 'rgba(0, 0, 0, 0.9)',
+        color: 'white',
+        padding: '25px',
+        borderRadius: '12px',
+        fontFamily: 'Arial, sans-serif',
+        fontSize: '16px',
+        lineHeight: '1.5',
+        maxWidth: '400px',
+        border: '2px solid rgba(76, 175, 80, 0.6)',
+        boxShadow: '0 8px 32px rgba(0, 0, 0, 0.8)',
+        zIndex: '1001'
+      }
+    });
+
+    // Set the HTML content
+    this.uiElement.setHTML(`
+      <div style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 15px;">
+        <div style="font-weight: bold; color: #4CAF50; font-size: 18px;">
+          🎮 Vehicle Game Controls
+        </div>
+        <button id="closeHints" style="
+          background: #f44336;
+          color: white;
+          border: none;
+          border-radius: 50%;
+          width: 30px;
+          height: 30px;
+          cursor: pointer;
+          font-size: 16px;
+          font-weight: bold;
+        ">×</button>
+      </div>
+      <div style="margin-bottom: 12px;">
+        <span style="color: #FFA726; font-weight: bold;">Movement:</span>
+        <br>• WASD or Arrow Keys - Move/Drive
+        <br>• Mouse - Camera control
+      </div>
+      <div style="margin-bottom: 12px;">
+        <span style="color: #FFA726; font-weight: bold;">Vehicle Interaction:</span>
+        <br>• E - Enter/Exit vehicle (when nearby)
+        <br>• F - Flip vehicle (when inside)
+      </div>
+      <div style="font-size: 14px; color: #CCCCCC; margin-top: 15px; text-align: center; font-style: italic;">
+        💡 Walk near a vehicle and press E to enter
+      </div>
+    `);
+
+    // Add close button functionality
+    const closeButton = this.uiElement.querySelector('#closeHints') as HTMLButtonElement;
+    if (closeButton) {
+      closeButton.addEventListener('click', () => {
+        this.removeHUD();
+      });
+    }
+
+    // Auto-close after 10 seconds
+    setTimeout(() => {
+      this.removeHUD();
+    }, 10000);
+  }
+
+  private removeHUD(): void {
+    if (this.uiElement) {
+      this.uiElement.remove();
+      this.uiElement = null;
+    }
+  }
+}