@jgengine/core 0.5.0 → 0.7.0

package/dist/physics/vehicleBody.d.ts

@@ -0,0 +1,93 @@
+import type { PhysicsWorld } from "./physicsWorld.js";
+import type { AxisInput } from "../input/axisInput.js";
+export interface GripCurve {
+    points: readonly (readonly [number, number])[];
+}
+/**
+ * Piecewise-linear tire-grip curve: normalized lateral slip → available grip (0..1). Grip peaks near
+ * the breakaway slip then falls off as the tire slides — the shape that separates a planted corner
+ * from a drift. Points are read in ascending slip order; ends clamp.
+ */
+export declare function sampleGripCurve(curve: GripCurve, slip: number): number;
+export declare const DEFAULT_GRIP_CURVE: GripCurve;
+export interface WheelSpec {
+    offset: readonly [number, number, number];
+    radius?: number;
+    restLength?: number;
+    steered?: boolean;
+    powered?: boolean;
+    handbrakeLocks?: boolean;
+}
+export interface WheelState {
+    worldX: number;
+    worldY: number;
+    worldZ: number;
+    grounded: boolean;
+    compression: number;
+    steerAngle: number;
+}
+export interface VehicleBodyConfig {
+    position: readonly [number, number, number];
+    heading?: number;
+    chassisHalfExtents?: readonly [number, number, number];
+    mass?: number;
+    wheels?: readonly WheelSpec[];
+    engineAccel?: number;
+    brakeAccel?: number;
+    topSpeed?: number;
+    reverseSpeed?: number;
+    turnRate?: number;
+    turnSpeedRef?: number;
+    grip?: GripCurve;
+    gripStrength?: number;
+    handbrakeGrip?: number;
+    rollingResistance?: number;
+    suspensionRest?: number;
+    suspensionStiffness?: number;
+    suspensionDamping?: number;
+    groundHeight?: (x: number, z: number) => number;
+    surfaceFriction?: (x: number, z: number) => number;
+}
+/**
+ * Arcade vehicle over the {@link PhysicsWorld} rigid-body sim. The chassis is a single box body driven
+ * by an {@link AxisInput}: per-wheel suspension is a spring-damper held with G3's `springJoint` against
+ * the sampled ground, drive/brake push along the heading, and a tire-grip curve bleeds lateral velocity
+ * (cornering, and drift under handbrake). Because the chassis is a physics body it still collides — that
+ * contact feeds crash damage. Call `update(dt, input)` before the shared `world.step(dt)`.
+ */
+export declare class VehicleBody {
+    heading: number;
+    readonly chassis: number;
+    private readonly world;
+    private readonly wheels;
+    private readonly springs;
+    private readonly wheelStates;
+    private readonly engineAccel;
+    private readonly brakeAccel;
+    private readonly topSpeed;
+    private readonly reverseSpeed;
+    private readonly turnRate;
+    private readonly turnSpeedRef;
+    private readonly grip;
+    private readonly gripStrength;
+    private readonly handbrakeGrip;
+    private readonly rollingResistance;
+    private readonly suspensionRest;
+    private readonly groundHeight;
+    private readonly surfaceFriction;
+    private groundedCount;
+    constructor(world: PhysicsWorld, config: VehicleBodyConfig);
+    private wheelMount;
+    get position(): [number, number, number];
+    get forward(): [number, number];
+    /** Signed forward speed along the heading (negative = reversing). */
+    get speed(): number;
+    get grounded(): boolean;
+    wheelState(index: number): WheelState | null;
+    get wheelCount(): number;
+    resetTo(position: readonly [number, number, number], heading: number): void;
+    update(dt: number, input: AxisInput): void;
+    private updateSuspension;
+    remove(): void;
+}
+export declare function createVehicleBody(world: PhysicsWorld, config: VehicleBodyConfig): VehicleBody;

package/dist/physics/vehicleBody.js

@@ -0,0 +1,234 @@
+/**
+ * Piecewise-linear tire-grip curve: normalized lateral slip → available grip (0..1). Grip peaks near
+ * the breakaway slip then falls off as the tire slides — the shape that separates a planted corner
+ * from a drift. Points are read in ascending slip order; ends clamp.
+ */
+export function sampleGripCurve(curve, slip) {
+    const pts = curve.points;
+    if (pts.length === 0)
+        return 1;
+    const s = Math.abs(slip);
+    if (s <= pts[0][0])
+        return pts[0][1];
+    for (let i = 1; i < pts.length; i += 1) {
+        const [x1, y1] = pts[i];
+        if (s <= x1) {
+            const [x0, y0] = pts[i - 1];
+            const span = x1 - x0;
+            const t = span <= 0 ? 0 : (s - x0) / span;
+            return y0 + (y1 - y0) * t;
+        }
+    }
+    return pts[pts.length - 1][1];
+}
+export const DEFAULT_GRIP_CURVE = {
+    points: [
+        [0, 1],
+        [0.2, 1],
+        [0.45, 0.78],
+        [1, 0.55],
+    ],
+};
+function cornerWheels(half, rest, radius) {
+    const x = half[0];
+    const z = half[2];
+    const y = -half[1];
+    return [
+        { offset: [-x, y, z], steered: true, restLength: rest, radius },
+        { offset: [x, y, z], steered: true, restLength: rest, radius },
+        { offset: [-x, y, -z], powered: true, handbrakeLocks: true, restLength: rest, radius },
+        { offset: [x, y, -z], powered: true, handbrakeLocks: true, restLength: rest, radius },
+    ];
+}
+/**
+ * Arcade vehicle over the {@link PhysicsWorld} rigid-body sim. The chassis is a single box body driven
+ * by an {@link AxisInput}: per-wheel suspension is a spring-damper held with G3's `springJoint` against
+ * the sampled ground, drive/brake push along the heading, and a tire-grip curve bleeds lateral velocity
+ * (cornering, and drift under handbrake). Because the chassis is a physics body it still collides — that
+ * contact feeds crash damage. Call `update(dt, input)` before the shared `world.step(dt)`.
+ */
+export class VehicleBody {
+    heading;
+    chassis;
+    world;
+    wheels;
+    springs;
+    wheelStates;
+    engineAccel;
+    brakeAccel;
+    topSpeed;
+    reverseSpeed;
+    turnRate;
+    turnSpeedRef;
+    grip;
+    gripStrength;
+    handbrakeGrip;
+    rollingResistance;
+    suspensionRest;
+    groundHeight;
+    surfaceFriction;
+    groundedCount = 0;
+    constructor(world, config) {
+        this.world = world;
+        this.heading = config.heading ?? 0;
+        const half = config.chassisHalfExtents ?? [0.9, 0.35, 1.8];
+        this.suspensionRest = config.suspensionRest ?? 0.55;
+        const radius = 0.35;
+        this.wheels = config.wheels ?? cornerWheels(half, this.suspensionRest, radius);
+        this.engineAccel = config.engineAccel ?? 18;
+        this.brakeAccel = config.brakeAccel ?? 26;
+        this.topSpeed = config.topSpeed ?? 28;
+        this.reverseSpeed = config.reverseSpeed ?? 10;
+        this.turnRate = config.turnRate ?? 1.6;
+        this.turnSpeedRef = config.turnSpeedRef ?? 8;
+        this.grip = config.grip ?? DEFAULT_GRIP_CURVE;
+        this.gripStrength = config.gripStrength ?? 8;
+        this.handbrakeGrip = config.handbrakeGrip ?? 0.35;
+        this.rollingResistance = config.rollingResistance ?? 0.6;
+        const stiffness = config.suspensionStiffness ?? 60;
+        const damping = config.suspensionDamping ?? 8;
+        this.groundHeight = config.groundHeight ?? (() => 0);
+        this.surfaceFriction = config.surfaceFriction ?? (() => 1);
+        this.chassis = world.addBody({
+            position: config.position,
+            halfExtents: half,
+            mass: config.mass ?? 4,
+        });
+        this.springs = [];
+        this.wheelStates = [];
+        for (const wheel of this.wheels) {
+            const worldPos = this.wheelMount(wheel);
+            const rest = wheel.restLength ?? this.suspensionRest;
+            const id = world.springJoint({
+                bodyA: this.chassis,
+                anchorA: [wheel.offset[0], wheel.offset[1], wheel.offset[2]],
+                anchorB: [worldPos[0], worldPos[1] - rest, worldPos[2]],
+                restLength: rest,
+                stiffness,
+                damping,
+            });
+            this.springs.push(id);
+            this.wheelStates.push({
+                worldX: worldPos[0],
+                worldY: worldPos[1],
+                worldZ: worldPos[2],
+                grounded: false,
+                compression: 0,
+                steerAngle: 0,
+            });
+        }
+    }
+    wheelMount(wheel) {
+        const sin = Math.sin(this.heading);
+        const cos = Math.cos(this.heading);
+        const [ox, oy, oz] = wheel.offset;
+        return [
+            this.world.posX[this.chassis] + ox * cos + oz * sin,
+            this.world.posY[this.chassis] + oy,
+            this.world.posZ[this.chassis] - ox * sin + oz * cos,
+        ];
+    }
+    get position() {
+        return [this.world.posX[this.chassis], this.world.posY[this.chassis], this.world.posZ[this.chassis]];
+    }
+    get forward() {
+        return [Math.sin(this.heading), Math.cos(this.heading)];
+    }
+    /** Signed forward speed along the heading (negative = reversing). */
+    get speed() {
+        const [fx, fz] = this.forward;
+        return this.world.velX[this.chassis] * fx + this.world.velZ[this.chassis] * fz;
+    }
+    get grounded() {
+        return this.groundedCount > 0;
+    }
+    wheelState(index) {
+        return this.wheelStates[index] ?? null;
+    }
+    get wheelCount() {
+        return this.wheels.length;
+    }
+    resetTo(position, heading) {
+        const w = this.world;
+        const c = this.chassis;
+        w.posX[c] = position[0];
+        w.posY[c] = position[1];
+        w.posZ[c] = position[2];
+        w.velX[c] = 0;
+        w.velY[c] = 0;
+        w.velZ[c] = 0;
+        this.heading = heading;
+        w.wake(c);
+    }
+    update(dt, input) {
+        const w = this.world;
+        const c = this.chassis;
+        this.updateSuspension(input.steer);
+        const speed = this.speed;
+        const grounded = this.groundedCount > 0;
+        if (grounded) {
+            const steerScale = Math.min(1, Math.abs(speed) / this.turnSpeedRef);
+            const dir = speed >= 0 ? 1 : -1;
+            this.heading += input.steer * this.turnRate * steerScale * dir * dt;
+        }
+        const [fx, fz] = this.forward;
+        if (grounded) {
+            let accel = 0;
+            if (input.throttle > 0 && speed < this.topSpeed)
+                accel += input.throttle * this.engineAccel;
+            if (input.brake > 0) {
+                if (speed > 0.2)
+                    accel -= input.brake * this.brakeAccel;
+                else if (speed > -this.reverseSpeed)
+                    accel -= input.brake * this.engineAccel;
+            }
+            w.velX[c] += fx * accel * dt;
+            w.velZ[c] += fz * accel * dt;
+            const roll = Math.max(0, 1 - this.rollingResistance * dt * (input.throttle > 0 ? 0 : 1));
+            const forwardSpeed = w.velX[c] * fx + w.velZ[c] * fz;
+            const rolled = forwardSpeed * roll;
+            const lateralSpeed = -w.velX[c] * fz + w.velZ[c] * fx;
+            const surface = this.surfaceFriction(w.posX[c], w.posZ[c]);
+            const slip = Math.abs(lateralSpeed) / (Math.abs(forwardSpeed) + 1);
+            const handbrake = 1 - input.handbrake * (1 - this.handbrakeGrip);
+            const grip = sampleGripCurve(this.grip, slip) * surface * handbrake;
+            const keep = Math.max(0, 1 - grip * this.gripStrength * dt);
+            const newLateral = lateralSpeed * keep;
+            w.velX[c] = fx * rolled - fz * newLateral;
+            w.velZ[c] = fz * rolled + fx * newLateral;
+            w.wake(c);
+        }
+    }
+    updateSuspension(steer) {
+        this.groundedCount = 0;
+        const w = this.world;
+        for (let i = 0; i < this.wheels.length; i += 1) {
+            const wheel = this.wheels[i];
+            const state = this.wheelStates[i];
+            const mount = this.wheelMount(wheel);
+            const radius = wheel.radius ?? 0.35;
+            const rest = wheel.restLength ?? this.suspensionRest;
+            const groundY = this.groundHeight(mount[0], mount[2]);
+            const gap = mount[1] - (groundY + radius);
+            const maxTravel = rest + radius;
+            const grounded = gap <= maxTravel;
+            w.setJointAnchor(this.springs[i], mount[0], groundY + radius, mount[2]);
+            state.worldX = mount[0];
+            state.worldY = groundY + radius;
+            state.worldZ = mount[2];
+            state.grounded = grounded;
+            state.compression = Math.max(0, rest - gap);
+            state.steerAngle = wheel.steered === true ? steer : 0;
+            if (grounded)
+                this.groundedCount += 1;
+        }
+    }
+    remove() {
+        for (const id of this.springs)
+            this.world.removeJoint(id);
+        this.springs.length = 0;
+    }
+}
+export function createVehicleBody(world, config) {
+    return new VehicleBody(world, config);
+}

package/dist/runtime/gameContext.d.ts

@@ -1,7 +1,10 @@
 import { type OnDeathSpec } from "../combat/death.js";
-import { type EffectInput, type EffectResult, type ReceiveMap, type SingleTargetEffectInput } from "../combat/effects.js";
+import { type EffectInput, type EffectResult, type EffectVia, type ReceiveMap, type SingleTargetEffectInput } from "../combat/effects.js";
 import { type ProjectileSystem } from "../combat/projectiles.js";
+import { type HitReaction, type HitReactionConfig } from "../combat/hitReaction.js";
+import { type TelegraphShape } from "../combat/telegraph.js";
 import { type CommandDefinition, type CommandResult } from "../commands/commandRegistry.js";
+import { type Cosmetics } from "../game/cosmetics.js";
 import type { GameDefinition } from "../game/defineGame.js";
 import { type GameEventMap, type GameEvents } from "../game/events.js";
 import { type GameFeed } from "../game/feed.js";
@@ -9,25 +12,35 @@ import { type Leaderboard } from "../game/leaderboard.js";
 import { type Loadouts } from "../game/loadout.js";
 import { type Drop, type LootTableDef } from "../game/lootTable.js";
 import { type QuestJournal } from "../game/quest.js";
+import { type WorldItemRecord, type WorldItemSpawnInput } from "../game/worldItem.js";
 import { type Social } from "../game/social.js";
 import { type TradeField, type TradeSystem } from "../game/trade.js";
 import { type Unlocks } from "../game/unlocks.js";
 import { type InventoryLayout, type InventorySet } from "../inventory/inventoryModel.js";
+import type { ContextVerb } from "../interaction/contextMenu.js";
 import type { ProximityPrompt } from "../interaction/proximityPrompt.js";
 import { type ItemUseHandler, type ItemUseInput, type ItemUseRejection, type ItemUseResult } from "../item/use.js";
 import { type WeaponStats } from "../item/weapon.js";
 import { type PoseAllowedStates, type PoseState } from "../movement/poseState.js";
 import type { ModelAssetRef } from "../scene/assetCatalog.js";
 import { type EntityStatsApi, type StatCatalog } from "../scene/entityStats.js";
-import type { EntityPose, SceneEntity, SpawnOptions } from "../scene/entityStore.js";
+import type { EntityPose, EntityPosition, SceneEntity, SpawnOptions } from "../scene/entityStore.js";
+import { type Forms } from "../scene/form.js";
 import { type ObjectStore } from "../scene/objectStore.js";
+import { type Roster } from "../scene/roster.js";
+import { type Possession } from "../scene/possession.js";
 import { type SpatialApi } from "../scene/spatial.js";
 import { type CycleTargetOptions } from "../scene/targeting.js";
 import { type Stats } from "../stats/statModifiers.js";
+import { type SimClock } from "../time/simClock.js";
 export interface GameContextItemEntry {
     use?: string;
     weapon?: Record<string, unknown>;
     trade?: TradeField;
+    /** Rarity id read by the `worldItem` loot-filter/render binding when this item drops to the ground (#32/#33). */
+    rarity?: string;
+    /** Base item type read by the loot-filter rule evaluator (#33); defaults to the item id when absent. */
+    baseType?: string;
 }
 export type CatalogEntityRole = "player" | "enemy" | "hostile" | "npc" | "vehicle";
 export interface GameContextEntityEntry {
@@ -38,6 +51,8 @@ export interface GameContextEntityEntry {
         walkSpeed?: number;
     };
     role?: CatalogEntityRole;
+    /** Right-click context-menu verbs for this entity (#31). */
+    verbs?: readonly ContextVerb[];
 }
 export interface GameContextObjectEntry {
     proximityPrompt?: ProximityPrompt;
@@ -45,6 +60,8 @@ export interface GameContextObjectEntry {
         baseBreakTime: number;
     };
     slotInventory?: InventoryLayout;
+    /** Right-click context-menu verbs for this object (#31). */
+    verbs?: readonly ContextVerb[];
 }
 export interface GameContextContent {
     itemById?(itemId: string): GameContextItemEntry | null | undefined;
@@ -69,6 +86,31 @@ export interface FloatTextInput {
     text?: string;
     kind?: string;
     amount?: number;
+    hitType?: string;
+    element?: string;
+    crit?: boolean;
+    scale?: number;
+}
+export interface TelegraphInput {
+    from: string;
+    shape: TelegraphShape;
+    at: [number, number, number];
+    dir?: number;
+    windupMs: number;
+    kind?: string;
+    effect?: {
+        effect: string;
+        via?: EffectVia;
+        radius?: number;
+        falloff?: "linear" | "none";
+        los?: boolean;
+    };
+}
+export interface HitReactionInput {
+    from: string;
+    to: string;
+    config: HitReactionConfig;
+    power?: number;
 }
 export interface SceneEntityContext {
     spawn(name: string, options?: SpawnOptions): string;
@@ -78,6 +120,8 @@ export interface SceneEntityContext {
     list(): readonly SceneEntity[];
     stats: EntityStatsApi;
     floatText(input: FloatTextInput): void;
+    telegraph(input: TelegraphInput): () => void;
+    hitReaction(input: HitReactionInput): HitReaction | null;
     setTarget(fromId: string, toId: string | null): void;
     getTarget(fromId: string): string | null;
     cycleTarget(fromId: string, options?: CycleTargetOptions): string | null;
@@ -92,6 +136,21 @@ export interface SceneEntityContext {
     hasLineOfSight: SpatialApi["hasLineOfSight"];
     queryArc: SpatialApi["queryArc"];
     moveToward: SpatialApi["moveToward"];
+    form: Forms;
+}
+export type WorldItemPickupResult = {
+    status: "ok";
+    record: WorldItemRecord;
+} | {
+    status: "rejected";
+    reason: string;
+};
+export interface SceneWorldItemContext {
+    spawn(input: WorldItemSpawnInput): WorldItemRecord;
+    get(instanceId: string): WorldItemRecord | null;
+    list(): readonly WorldItemRecord[];
+    nearestInRadius(from: EntityPosition, radius: number, filter?: (record: WorldItemRecord) => boolean): string | null;
+    pickup(instanceId: string, userId: string): WorldItemPickupResult;
 }
 export interface GameContextCommands {
     define<TInput>(name: string, definition: CommandDefinition<GameContext, TInput>): void;
@@ -125,6 +184,7 @@ export interface GameContext {
     scene: {
         object: SceneObjectContext;
         entity: SceneEntityContext;
+        worldItem: SceneWorldItemContext;
     };
     game: {
         commands: GameContextCommands;
@@ -137,6 +197,7 @@ export interface GameContext {
         unlocks: Unlocks;
         economy: GameContextEconomy;
         leaderboard: Leaderboard;
+        roster: Roster;
     };
     player: {
         userId: string;
@@ -148,11 +209,14 @@ export interface GameContext {
             reason: string;
         } | null;
         movement: PoseState;
+        possession: Possession;
+        cosmetics: Cosmetics;
     };
     item: {
         use: GameContextItemUse;
         weapon: WeaponStats;
     };
+    time: SimClock;
     subscribe(listener: () => void): () => void;
     version(): number;
 }