@threenative/core 0.3.5 → 0.3.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1515,9 +1515,21 @@ interface IGameRuntimeObservations {
1515
1515
  contributions(): readonly IGameObservationContribution[];
1516
1516
  }
1517
1517
  interface IGamePluginRuntime {
1518
+ /**
1519
+ * Runs `ticks` fixed steps and returns how many ran. Fewer than asked when a `goto()` began
1520
+ * inside the batch: the ticks after it belong to the destination scene, which does not exist
1521
+ * until `sceneTransition()` settles.
1522
+ */
1518
1523
  readonly fixedStep: (ticks: number, options?: {
1519
1524
  render?: boolean;
1520
1525
  }) => number;
1526
+ /**
1527
+ * The `goto()` in flight, or undefined when no scene is loading. Settles once the destination
1528
+ * scene has loaded and entered, and never rejects: a failed load is reported as a launch
1529
+ * failure. A runner that counts ticks awaits it before spending more, exactly as it awaits
1530
+ * `holdStart` at boot, so a restart cannot be outrun by the ticks that follow it.
1531
+ */
1532
+ readonly sceneTransition?: () => Promise<void> | undefined;
1521
1533
  /** Completed scene updates and primary world render requests, independent of budget windows. */
1522
1534
  readonly frameCounts?: () => {
1523
1535
  updates: number;
package/dist/hot.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { a as audioRuntimeSnapshot } from './audio-DIJE5HTr.js';
2
- import { I as IGame } from './game-Bj8G1wmD.js';
2
+ import { I as IGame } from './game-Jz4Fdoeb.js';
3
3
  import 'three';
4
4
  import './assets-CqvE429w.js';
5
5
  import './renderer-9yEo9hPa.js';
package/dist/index.d.ts CHANGED
@@ -3,8 +3,8 @@ import { Object3D, AnimationClip, AnimationMixer, Vector3, Camera, Group, Matrix
3
3
  export { I as IAssetLoader, a as IAssetLoaderOptions, b as ITextureOptions, c as createAssetLoader, r as reconcileMirroredClips } from './assets-CqvE429w.js';
4
4
  export { A as AudioBus, I as IAudioBusOptions, b as IAudioCompressorOptions, c as IAudioPlayOptions, r as resetAudioCueLedger } from './audio-DIJE5HTr.js';
5
5
  export { C as CanvasLayer } from './canvas-layer-C1-5CviZ.js';
6
- import { b as IGamePluginRuntime, a as IGamePluginHooks } from './game-Bj8G1wmD.js';
7
- export { A as AfterPhysicsCallback, C as ContextMenuPolicy, G as GEOMETRY_ASSET_KEY, c as GEOMETRY_CAPTURE_DEFAULT_LIMIT, d as GEOMETRY_CAPTURE_MAX_LIMIT, e as GEOMETRY_CAPTURE_SORTS, f as GEOMETRY_CAPTURE_TIMEOUT_MS, g as GEOMETRY_CAPTURE_WALK_CAP, h as GeometryCaptureSort, i as ICtx, I as IGame, j as IGameObservationContribution, k as IGameObservationSampleRequest, l as IGamePlatformSource, m as IGeometryCaptureAsset, n as IGeometryCaptureMesh, o as IGeometryCapturePass, p as IGeometryCaptureReport, q as IGeometryCaptureRequest, r as IGeometryCaptureRow, s as IInputAction, t as IInputGamepad, u as IPointerDragHandle, v as IPointerEvent3D, w as IPointerEvents3D, x as IPointerEvents3DOptions, y as IPointerEvents3DPicker, z as IPointerState, B as IRandom, D as IRawInputPointer, E as IRawInputPointerEdge, F as IRawInputState, H as IRaycastOptions, J as IScenePickerOptions, K as IThreeNativeAudioConfig, L as IThreeNativeAudioLoop, M as IThreeNativeAudioOverride, N as IThreeNativeAudioSpectrum, O as IThreeNativeBootSplash, P as IThreeNativeConfig, Q as IThreeNativeIconVariants, R as IThreeNativeLodConfig, S as IThreeNativeLodGenerationConfig, T as IThreeNativeLodOverride, U as IThreeNativeLodRuntimeConfig, V as IThreeNativeTexturesConfig, W as ITweenOptions, X as IWarmUpCacheOptions, Y as IWarmUpObservation, Z as IWarmUpOptions, _ as IWarmUpProgress, $ as IWarmUpRenderer, a0 as IWarmUpReport, a1 as InputBindings, a2 as InputMap, a3 as InputPlatformSource, a4 as PointerEvent3DListener, a5 as PointerEvent3DType, a6 as PointerEvents3D, a7 as Scene, a8 as SceneFrame, a9 as ScenePicker, aa as ScheduleHandle, ab as Scheduler, ac as ThreeNativeBackgroundMode, ad as ThreeNativeLodMinTrianglesScope, ae as ThreeNativeLodPreset, af as ThreeNativeOrientation, ag as ThreeNativeUiRenderer, ah as WarmUpCacheStatus, ai as WarmUpObservationStatus, aj as afterPhysics, ak as captureMouse, al as createRandom, am as defineGame, an as warmUpScene } from './game-Bj8G1wmD.js';
6
+ import { b as IGamePluginRuntime, a as IGamePluginHooks } from './game-Jz4Fdoeb.js';
7
+ export { A as AfterPhysicsCallback, C as ContextMenuPolicy, G as GEOMETRY_ASSET_KEY, c as GEOMETRY_CAPTURE_DEFAULT_LIMIT, d as GEOMETRY_CAPTURE_MAX_LIMIT, e as GEOMETRY_CAPTURE_SORTS, f as GEOMETRY_CAPTURE_TIMEOUT_MS, g as GEOMETRY_CAPTURE_WALK_CAP, h as GeometryCaptureSort, i as ICtx, I as IGame, j as IGameObservationContribution, k as IGameObservationSampleRequest, l as IGamePlatformSource, m as IGeometryCaptureAsset, n as IGeometryCaptureMesh, o as IGeometryCapturePass, p as IGeometryCaptureReport, q as IGeometryCaptureRequest, r as IGeometryCaptureRow, s as IInputAction, t as IInputGamepad, u as IPointerDragHandle, v as IPointerEvent3D, w as IPointerEvents3D, x as IPointerEvents3DOptions, y as IPointerEvents3DPicker, z as IPointerState, B as IRandom, D as IRawInputPointer, E as IRawInputPointerEdge, F as IRawInputState, H as IRaycastOptions, J as IScenePickerOptions, K as IThreeNativeAudioConfig, L as IThreeNativeAudioLoop, M as IThreeNativeAudioOverride, N as IThreeNativeAudioSpectrum, O as IThreeNativeBootSplash, P as IThreeNativeConfig, Q as IThreeNativeIconVariants, R as IThreeNativeLodConfig, S as IThreeNativeLodGenerationConfig, T as IThreeNativeLodOverride, U as IThreeNativeLodRuntimeConfig, V as IThreeNativeTexturesConfig, W as ITweenOptions, X as IWarmUpCacheOptions, Y as IWarmUpObservation, Z as IWarmUpOptions, _ as IWarmUpProgress, $ as IWarmUpRenderer, a0 as IWarmUpReport, a1 as InputBindings, a2 as InputMap, a3 as InputPlatformSource, a4 as PointerEvent3DListener, a5 as PointerEvent3DType, a6 as PointerEvents3D, a7 as Scene, a8 as SceneFrame, a9 as ScenePicker, aa as ScheduleHandle, ab as Scheduler, ac as ThreeNativeBackgroundMode, ad as ThreeNativeLodMinTrianglesScope, ae as ThreeNativeLodPreset, af as ThreeNativeOrientation, ag as ThreeNativeUiRenderer, ah as WarmUpCacheStatus, ai as WarmUpObservationStatus, aj as afterPhysics, ak as captureMouse, al as createRandom, am as defineGame, an as warmUpScene } from './game-Jz4Fdoeb.js';
8
8
  import * as three_webgpu from 'three/webgpu';
9
9
  import { StorageTexture, ComputeNode, UniformNode, Node, TextureNode, NodeMaterial, StorageBufferNode, StructTypeNode, Data3DTexture, ShadowBaseNode, NodeBuilder, NodeFrame, SpriteNodeMaterial, StorageTextureNode, Storage3DTexture } from 'three/webgpu';
10
10
  import { I as IRendererLike, F as FramePassKind, a as IFrameBudgetWindow } from './renderer-9yEo9hPa.js';
@@ -4236,6 +4236,6 @@ declare function boneLengthDeviations(root: Object3D, bind: IBoneLengthSnapshot,
4236
4236
  * unavoidable here — core is bundled for browsers and cannot read `package.json` at runtime — so
4237
4237
  * the spec now asserts this equals the manifest instead of asserting a number somebody typed.
4238
4238
  */
4239
- declare const version = "0.3.5";
4239
+ declare const version = "0.3.6";
4240
4240
 
4241
4241
  export { ATLAS_PADDING, ATMOSPHERE_LUT_RESOLUTIONS, AnimationComposer, AnimationPlayer, Atmosphere, type AtmosphereDirection, AtmosphereLuts, type AtmosphereRgb, Billboard3D, type BillboardLockAxis, BlendSpace1D, BlendSpace2D, CameraShake, type CameraShakeCurve, ClusteredBatch, ClusteredMesh, Daylight, ENVIRONMENT_TOO_SMALL_MARKER, FlightModel, FluidField2D, FluidParticles3D, FramePassKind, GPUParticles3D, GPUSceneBVH, type GPUSceneBVHTraceFunction, GroundSnap, type IAddInSlicesOptions, type IAddInSlicesProgress, type IAddInSlicesReport, type IAircraftAirframe, type IAnimationComposerOptions, type IAnimationLayer, type IAnimationMask, type IAnimationMotionDelta, type IAnimationPlayOptions, type IAnimationPlayerOptions, type IAnimationRootMotionOptions, type IAtmosphereLutResolution, type IAtmosphereLutResolutions, type IAtmosphereOptions, type IAtmosphereParameterPatch, type IAtmosphereParameters, type IAtmosphereScenePass, type IBillboard3DOptions, type IBoneContactReport, type IBoneLengthDeviation, type IBoneLengthDeviationReport, type IBoneLengthDeviationsOptions, type IBoneLengthSnapshot, type IBonePoseError, type ICameraShakeOffset, type ICameraShakeOptions, type IClipBindingReport, type IClipCoverageReport, type IClipPoseErrorOptions, type IClipPoseErrorReport, type IClipPoseSubject, type IClipTrackBinding, type IClusterTable, type IClusteredBatchBuildOptions, type IClusteredBatchOptions, type IClusteredMeshOptions, type IClusteredPlacement, IComputeDriven$1 as IComputeDriven, type IDaylightOptions, type IEmitParticleRequest, type IFlightAxes, type IFlightControls, type IFlightDeck, type IFlightEnvironment, type IFlightForces, type IFlightModelOptions, type IFlightModifiers, type IFlightQuaternion, type IFlightState, type IFlightVector3, type IFluidBounds, type IFluidCollider, type IFluidFieldOptions, type IFluidFieldSampler, type IFluidFieldVector2, type IFluidParticlesOptions, type IFluidParticlesStats, IFrameBudgetWindow, type IGPUParticles3DOptions, type IGPUParticles3DRuntime, type IGPUParticles3DSpawnBuffers, type IGPUParticles3DSpawnRequest, type IGPUParticles3DStats, IGPUReadbackSample, type IGPUSceneBVHMaterialGroup, type IGPUSceneBVHOptions, IGamePluginHooks, IGamePluginRuntime, type IGroundSnapOptions, type IInstancedBatchBuildOptions, type IInstancedBatchOptions, type IInstancedPlacement, type ILaunchFailure, type ILoadAllOptions, type ILoadAllProgress, type IMatrixWorldReport, type IMeasureThreePoseOptions, type IMergeByMaterialOptions, type IMergePart, type IMergePartsOptions, type INormaliseToMetresOptions, type IPathFollow3DOptions, type IPathFollow3DProjection, type IPathFollow3DSample, type IProbeVolumeBakeProgress, type IProbeVolumeCoefficient, type IProbeVolumeObservation, type IProbeVolumeOptions, type IReplayOptions, type IReplayRecording, type IReplayRecordingSample, type IResolvedAtmosphereParameters, type IRippleFieldFlow, type IRippleFieldOptions, type ISceneShape, type ISceneWarning, type ISkeletalMesh3DOptions, type ISoftBody3DOptions, type ISoftBodyCollision, type ISolarPosition, type ISolarPositionInput, type ISpanProbeTarget, type ISpanSummary, type ISpanWindow, type ISpectralOceanCascade, type ISpectralOceanHeight, type ISpectralOceanOptions, type ISpriteAnimator3DOptions, type ISpriteFrame3D, type IStaticTransformCensus, type IStrideReport, type IThreePoseBounds, type IThreePoseMeasurement, type ITracerPool3DOptions, type ITracerSpawnOptions, type IUnlitFoliageWarning, type IValidationReport, type IVirtualShadowOptions, type IVirtualShadowStats, type IWaterReflectionOptions, type IWaterSurfaceOptions, type IWaveFieldDomainWarp, type IWaveFieldGraphOptions, type IWaveFieldOptions, type IWaveFieldSample, type IWaveFieldWave, InstancedBatch, LUT_RESOLUTIONS, type LaunchFailureKind, type MatrixWorldMode, MatrixWorldPass, NEUTRAL_FLIGHT_MODIFIERS, type NormaliseAxis, OPACITY_IGNORED_MARKER, PROBE_VOLUME_MARKER, PathFollow3D, ProbeVolume, type ProbeVolumeDensity, RENDERLIST_VALIDATE_FLAG, RENDERLIST_VALIDATE_MARKER, type Recording, RenderListValidator, type ReplayPointer, RippleField, SCENE_WARNING_MARKER, SPANS, SPANS_FLAG, SPANS_MARKER, SPAN_COUNT, SPAN_NAMES, STATIC_TRANSFORM_MARKER, SkeletalMesh3D, SoftBody3D, type SpanId, SpanRecorder, SpectralOcean, SpriteAnimator3D, type SpritePlaybackMode, type ThreePoseQuaternion, type ThreePoseVector, TracerPool3D, UNLIT_FOLIAGE_FIX, UNLIT_FOLIAGE_MARKER, VIRTUAL_SHADOW_CASTER_LAYER, VIRTUAL_SHADOW_MARKER, VIRTUAL_SHADOW_MOVER_LAYER, VIRTUAL_SHADOW_WIDE_CASTER_LAYER, VirtualShadowNode, WaterSurface3D, type WaveDirection, WaveField, addInSlices, addSpan, aerodynamicCoefficients, airDensity, aircraftMass, alwaysRender, attachToBone, attitudeAxes, beginSpan, boneContact, boneLengthDeviations, boneLengths, bvhIntersectFirstHit, clipBoneCoverage, clipPoseError, clipTrackBindings, createReplayDriver, debugFlag, describeSceneShape, describeSceneWarning, directionFromSolarPosition, directionalTransmittance, displayPeriodMs, endSpan, exposeDebug, formatSceneWarning, formatSpansWindow, formatUnlitFoliageWarning, formatValidationReport, gearClearance, installSpanProbes, invalidateStatic, isStatic, loadAll, markStatic, measureThreePose, mergeByMaterial, mergeParts, normaliseToMetres, onLaunchFailure, parseReplayRecording, posedBounds, rayStruct, readProbeVolumeObservation, readVirtualShadowMarker, refreshStaticTransforms, renderListValidationRequested, renderTrapAudit, replay, resetStaticTransforms, resolveAtmosphereLutResolutions, resolveAtmosphereParameters, sceneWarning, setAttitude, setSpanRecorder, skeletonBones, softCircleDataTexture, solarPosition, solarPositionAt, spanNow, spanRecorder, spansRequested, staticTransformCensus, unlitFoliageWarning, unmarkStatic, updateAtmosphereParameters, updateClusteredMeshes, validateWorldMatrices, version, zenithTransmittance };
package/dist/index.js CHANGED
@@ -8088,6 +8088,10 @@ var FixedStepLoop = class {
8088
8088
  }
8089
8089
  return updates;
8090
8090
  }
8091
+ /**
8092
+ * Run `ticks` fixed steps now and return how many ran. `until` is asked after each tick and ends
8093
+ * the batch early when it answers true, so a caller can stop where an asynchronous change began.
8094
+ */
8091
8095
  advance(ticks, options) {
8092
8096
  if (!this.#running) throw new Error("Cannot advance a stopped loop.");
8093
8097
  if (!Number.isInteger(ticks) || ticks <= 0)
@@ -8099,22 +8103,28 @@ var FixedStepLoop = class {
8099
8103
  this.#driven = true;
8100
8104
  if (this.#frameHandle !== void 0) this.#cancelFrame(this.#frameHandle);
8101
8105
  this.#frameHandle = void 0;
8102
- for (let index = 0; index < ticks; index += 1) this.stepFrame(this.#now(), true);
8106
+ for (let index = 0; index < ticks; index += 1) {
8107
+ this.stepFrame(this.#now(), true);
8108
+ if (options.until?.() === true) return index + 1;
8109
+ }
8103
8110
  return ticks;
8104
8111
  }
8105
8112
  const startedAt = this.#now();
8106
- for (let index = 0; index < ticks; index += 1) {
8113
+ let ran = 0;
8114
+ while (ran < ticks) {
8107
8115
  this.#interpolation?.beginTick();
8108
8116
  this.#onUpdate(this.step);
8109
8117
  this.#onAfterPhysics(this.step);
8110
8118
  this.#interpolation?.endTick();
8111
8119
  this.#tick += 1;
8120
+ ran += 1;
8121
+ if (options?.until?.() === true) break;
8112
8122
  }
8113
8123
  const finishedAt = this.#now();
8114
8124
  const budget = this.#budget;
8115
8125
  if (budget !== void 0 && Number.isFinite(startedAt) && Number.isFinite(finishedAt))
8116
- budget.addSimulation(Math.max(0, finishedAt - startedAt), ticks);
8117
- return ticks;
8126
+ budget.addSimulation(Math.max(0, finishedAt - startedAt), ran);
8127
+ return ran;
8118
8128
  }
8119
8129
  /**
8120
8130
  * Draw the world once without stepping it, for a native deterministic screenshot: the automatic
@@ -14608,7 +14618,7 @@ var GpuFrameObservation = class {
14608
14618
  };
14609
14619
 
14610
14620
  // src/version.ts
14611
- var CORE_VERSION = "0.3.5";
14621
+ var CORE_VERSION = "0.3.6";
14612
14622
 
14613
14623
  // src/pipeline-census.ts
14614
14624
  var PIPELINE_CENSUS_VERSION = 1;
@@ -20389,7 +20399,11 @@ var GameImpl = class {
20389
20399
  this.#loop = gameLoop;
20390
20400
  const startGates = [];
20391
20401
  const runtime = {
20392
- fixedStep: (ticks, options) => gameLoop.advance(ticks, options),
20402
+ fixedStep: (ticks, options) => gameLoop.advance(ticks, { ...options, until: () => this.#pendingSceneEnter !== void 0 }),
20403
+ sceneTransition: () => this.#pendingSceneEnter?.then(
20404
+ () => void 0,
20405
+ () => void 0
20406
+ ),
20393
20407
  frameCounts: () => ({ updates, renders }),
20394
20408
  frameBudgetWindow: () => this.#frameBudget?.window(),
20395
20409
  freezeClock: () => gameLoop.freezeClock(),
@@ -31630,7 +31644,7 @@ function boneLengthDeviations(root, bind, options = {}) {
31630
31644
  }
31631
31645
 
31632
31646
  // src/index.ts
31633
- var version = "0.3.5";
31647
+ var version = "0.3.6";
31634
31648
  /*!
31635
31649
  * Selectively adapted from GGEZ packages/anim-runtime/src/runtime/helpers.ts
31636
31650
  * (findBlend1DChildren, computeTriangleBarycentricWeights, findBlend2DEdgeWeights)
@@ -1,6 +1,6 @@
1
1
  import { JsonValue, JsonPrimitive } from '@threenative/playtest/protocol';
2
2
  export { PLAYTEST_CLOCK_GLOBAL } from '@threenative/playtest/protocol';
3
- import { a as IGamePluginHooks } from './game-Bj8G1wmD.js';
3
+ import { a as IGamePluginHooks } from './game-Jz4Fdoeb.js';
4
4
  import './assets-CqvE429w.js';
5
5
  import 'three';
6
6
  import './renderer-9yEo9hPa.js';
package/dist/playtest.js CHANGED
@@ -43,7 +43,7 @@ new Vector3();
43
43
  new Vector3();
44
44
 
45
45
  // src/version.ts
46
- var CORE_VERSION = "0.3.5";
46
+ var CORE_VERSION = "0.3.6";
47
47
 
48
48
  // src/pipeline-census.ts
49
49
  var PIPELINE_CENSUS_CAPABILITY = "runtime.pipelineCensus";
@@ -112,7 +112,17 @@ function playtest(options = {}) {
112
112
  // The live clock has to be driven by the host's own frame pump, so a live run's `advance`
113
113
  // waits the span of wall time the count names and reports the ticks that pump ran.
114
114
  ...runtime === void 0 ? {} : {
115
- fixedStep: (ticks, options2) => clockMode === "wall-clock" && liveAdvance !== void 0 ? liveAdvance(ticks) : runtime.fixedStep(ticks, options2),
115
+ fixedStep: async (ticks, options2) => {
116
+ await runtime.sceneTransition?.();
117
+ if (clockMode === "wall-clock" && liveAdvance !== void 0)
118
+ return liveAdvance(ticks);
119
+ let ran = runtime.fixedStep(ticks, options2);
120
+ while (ran > 0 && ran < ticks) {
121
+ await runtime.sceneTransition?.();
122
+ ran += runtime.fixedStep(ticks - ran, options2);
123
+ }
124
+ return ran;
125
+ },
116
126
  tick: runtime.tick
117
127
  },
118
128
  ...runtime?.runtimeDiagnosticsSeries === void 0 ? {} : { runtimeDiagnosticsSeries: runtime.runtimeDiagnosticsSeries },
@@ -439,7 +439,7 @@ async function runRecipe(name, request, options = {}) {
439
439
 
440
440
  // src/index.ts
441
441
  var SERVER_NAME = "threenative-blender-mcp";
442
- var SERVER_VERSION = "0.1.5";
442
+ var SERVER_VERSION = "0.1.6";
443
443
  var AUTHORING_INSTRUCTIONS = "Call blender_status before anything else: it answers whether this machine can convert models at all, and when it cannot it names the install command rather than failing. Blender is never installed for the user \u2014 ask first, then let them run the command. An .fbx, .blend, .obj or .dae placed in a game's assets directory is converted by the build itself; these tools are for inspecting a source before committing it and for operations the build does not perform. For anything no named tool covers, read a shipped recipe with blender_recipes and adapt it, then run it with blender_run_python.";
444
444
  var TOOL_DEFINITIONS = [
445
445
  {
@@ -524,7 +524,7 @@ function handleLine(line, manifestFile) {
524
524
  capabilities: { tools: { listChanged: false } },
525
525
  instructions: AUTHORING_INSTRUCTIONS,
526
526
  protocolVersion: "2025-06-18",
527
- serverInfo: { name: "threenative-engine-mcp", version: "0.2.5" }
527
+ serverInfo: { name: "threenative-engine-mcp", version: "0.2.6" }
528
528
  });
529
529
  }
530
530
  if (request.method === "tools/list") {
package/mcp/servers.mjs CHANGED
@@ -40,8 +40,8 @@ export const MCP_SERVERS = Object.freeze({
40
40
  export const MCP_PACKAGES = Object.freeze({
41
41
  assets: Object.freeze({ name: "threenative-asset-mcp", version: "0.14.0" }),
42
42
  sculpt: Object.freeze({ name: "threenative-sculpt-mcp", version: "0.2.2" }),
43
- engine: Object.freeze({ name: "threenative-engine-mcp", version: "0.2.5" }),
44
- blender: Object.freeze({ name: "threenative-blender-mcp", version: "0.1.5" }),
43
+ engine: Object.freeze({ name: "threenative-engine-mcp", version: "0.2.6" }),
44
+ blender: Object.freeze({ name: "threenative-blender-mcp", version: "0.1.6" }),
45
45
  });
46
46
 
47
47
  /** How one host spells a stdio MCP server. Hosts agree on what to run and disagree on where to
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@threenative/core",
3
- "version": "0.3.5",
3
+ "version": "0.3.6",
4
4
  "license": "MIT AND GPL-2.0-or-later",
5
5
  "description": "The small vanilla Three.js game runtime foundation.",
6
6
  "keywords": [
@@ -95,12 +95,12 @@
95
95
  "tsup": "8.5.1",
96
96
  "typescript": "npm:@typescript/typescript6@6.0.2",
97
97
  "@typescript/native": "npm:typescript@7.0.2",
98
- "threenative-blender-mcp": "0.1.5",
99
- "threenative-engine-mcp": "0.2.5",
100
- "@threenative/playtest": "0.3.5"
98
+ "threenative-engine-mcp": "0.2.6",
99
+ "threenative-blender-mcp": "0.1.6",
100
+ "@threenative/playtest": "0.3.6"
101
101
  },
102
102
  "peerDependencies": {
103
- "@threenative/playtest": ">=0.3.5 <0.4.0",
103
+ "@threenative/playtest": ">=0.3.6 <0.4.0",
104
104
  "react": ">=19.2.0 <20",
105
105
  "react-reconciler": ">=0.33.0 <0.34"
106
106
  },
package/src/game.ts CHANGED
@@ -151,7 +151,19 @@ export interface IGameRuntimeObservations {
151
151
  }
152
152
 
153
153
  export interface IGamePluginRuntime {
154
+ /**
155
+ * Runs `ticks` fixed steps and returns how many ran. Fewer than asked when a `goto()` began
156
+ * inside the batch: the ticks after it belong to the destination scene, which does not exist
157
+ * until `sceneTransition()` settles.
158
+ */
154
159
  readonly fixedStep: (ticks: number, options?: { render?: boolean }) => number;
160
+ /**
161
+ * The `goto()` in flight, or undefined when no scene is loading. Settles once the destination
162
+ * scene has loaded and entered, and never rejects: a failed load is reported as a launch
163
+ * failure. A runner that counts ticks awaits it before spending more, exactly as it awaits
164
+ * `holdStart` at boot, so a restart cannot be outrun by the ticks that follow it.
165
+ */
166
+ readonly sceneTransition?: () => Promise<void> | undefined;
155
167
  /** Completed scene updates and primary world render requests, independent of budget windows. */
156
168
  readonly frameCounts?: () => { updates: number; renders: number };
157
169
  /**
@@ -2072,7 +2084,13 @@ class GameImpl<TState extends Record<string, unknown>, TPhysics>
2072
2084
  readonly resolveEntered: () => void;
2073
2085
  }> = [];
2074
2086
  const runtime: IGamePluginRuntime = {
2075
- fixedStep: (ticks, options) => gameLoop.advance(ticks, options),
2087
+ fixedStep: (ticks, options) =>
2088
+ gameLoop.advance(ticks, { ...options, until: () => this.#pendingSceneEnter !== undefined }),
2089
+ sceneTransition: () =>
2090
+ this.#pendingSceneEnter?.then(
2091
+ () => undefined,
2092
+ () => undefined,
2093
+ ),
2076
2094
  frameCounts: () => ({ updates, renders }),
2077
2095
  frameBudgetWindow: () => this.#frameBudget?.window(),
2078
2096
  freezeClock: () => gameLoop.freezeClock(),
package/src/index.ts CHANGED
@@ -6,7 +6,7 @@
6
6
  * unavoidable here — core is bundled for browsers and cannot read `package.json` at runtime — so
7
7
  * the spec now asserts this equals the manifest instead of asserting a number somebody typed.
8
8
  */
9
- export const version = "0.3.5";
9
+ export const version = "0.3.6";
10
10
 
11
11
  /**
12
12
  * Play a skinned or sprite animation from game code.
package/src/loop.ts CHANGED
@@ -493,7 +493,11 @@ export class FixedStepLoop {
493
493
  return updates;
494
494
  }
495
495
 
496
- advance(ticks: number, options?: { render?: boolean }): number {
496
+ /**
497
+ * Run `ticks` fixed steps now and return how many ran. `until` is asked after each tick and ends
498
+ * the batch early when it answers true, so a caller can stop where an asynchronous change began.
499
+ */
500
+ advance(ticks: number, options?: { render?: boolean; until?: () => boolean }): number {
497
501
  if (!this.#running) throw new Error("Cannot advance a stopped loop.");
498
502
  if (!Number.isInteger(ticks) || ticks <= 0)
499
503
  throw new Error("advance ticks must be a positive integer.");
@@ -511,7 +515,10 @@ export class FixedStepLoop {
511
515
  this.#driven = true;
512
516
  if (this.#frameHandle !== undefined) this.#cancelFrame(this.#frameHandle);
513
517
  this.#frameHandle = undefined;
514
- for (let index = 0; index < ticks; index += 1) this.stepFrame(this.#now(), true);
518
+ for (let index = 0; index < ticks; index += 1) {
519
+ this.stepFrame(this.#now(), true);
520
+ if (options.until?.() === true) return index + 1;
521
+ }
515
522
  return ticks;
516
523
  }
517
524
  // A counted batch is metered, because a tick-counted run — which is what a playtest run is — is
@@ -522,18 +529,21 @@ export class FixedStepLoop {
522
529
  // percentiles. `addSimulation` decides which it is from the frame it lands in, so an `advance()`
523
530
  // from inside a live frame — the frozen prime's settle — is charged there exactly once.
524
531
  const startedAt = this.#now();
525
- for (let index = 0; index < ticks; index += 1) {
532
+ let ran = 0;
533
+ while (ran < ticks) {
526
534
  this.#interpolation?.beginTick();
527
535
  this.#onUpdate(this.step);
528
536
  this.#onAfterPhysics(this.step);
529
537
  this.#interpolation?.endTick();
530
538
  this.#tick += 1;
539
+ ran += 1;
540
+ if (options?.until?.() === true) break;
531
541
  }
532
542
  const finishedAt = this.#now();
533
543
  const budget = this.#budget;
534
544
  if (budget !== undefined && Number.isFinite(startedAt) && Number.isFinite(finishedAt))
535
- budget.addSimulation(Math.max(0, finishedAt - startedAt), ticks);
536
- return ticks;
545
+ budget.addSimulation(Math.max(0, finishedAt - startedAt), ran);
546
+ return ran;
537
547
  }
538
548
 
539
549
  /**
package/src/playtest.ts CHANGED
@@ -100,10 +100,21 @@ export function playtest<
100
100
  ...(runtime === undefined
101
101
  ? {}
102
102
  : {
103
- fixedStep: (ticks, options) =>
104
- clockMode === "wall-clock" && liveAdvance !== undefined
105
- ? liveAdvance(ticks)
106
- : runtime.fixedStep(ticks, options),
103
+ fixedStep: async (ticks, options) => {
104
+ // A `goto()` loads asynchronously and a counted batch is synchronous, so ticks
105
+ // spent while it loads simulate no world: a restart is outrun and the run reads
106
+ // a scene that never entered. Counted ticks wait for the scene that owns them.
107
+ await runtime.sceneTransition?.();
108
+ if (clockMode === "wall-clock" && liveAdvance !== undefined)
109
+ return liveAdvance(ticks);
110
+ let ran = runtime.fixedStep(ticks, options);
111
+ // The batch ends early when a `goto()` began inside it; the rest follows the world.
112
+ while (ran > 0 && ran < ticks) {
113
+ await runtime.sceneTransition?.();
114
+ ran += runtime.fixedStep(ticks - ran, options);
115
+ }
116
+ return ran;
117
+ },
107
118
  tick: runtime.tick,
108
119
  }),
109
120
  ...(runtime?.runtimeDiagnosticsSeries === undefined
package/src/version.ts CHANGED
@@ -1,2 +1,2 @@
1
1
  // Generated by scripts/generate-version.mjs - do not edit. Source: package.json.
2
- export const CORE_VERSION = "0.3.5";
2
+ export const CORE_VERSION = "0.3.6";