@bendyline/molen-ambient 0.0.11 → 0.0.13

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.
@@ -31,7 +31,7 @@ const KIND_SPEED = {
31
31
  function classifyFeature(feature) {
32
32
  const cls = feature.class.toLowerCase();
33
33
  const sub = (feature.subclass ?? "").toLowerCase();
34
- if (cls === "aeroway" || /runway|taxiway|apron/.test(sub)) return sub === "runway" || cls === "runway" ? "runway" : void 0;
34
+ if (/^(aeroway|runway|taxiway|taxilane|parking_position)$/.test(cls) || /^(runway|taxiway|taxilane|apron|parking_position)$/.test(sub)) return sub === "runway" || cls === "runway" ? "runway" : void 0;
35
35
  if (cls === "ferry" || sub === "ferry") return {
36
36
  class: "water",
37
37
  kind: "ferry"
@@ -175,16 +175,38 @@ function roadLanes(feature, width) {
175
175
  if (feature.oneway === true && feature.lanes === void 0) total = dmath.max(1, dmath.min(total, dmath.round(width / 3.3)));
176
176
  return { total: dmath.max(minimum, total) };
177
177
  }
178
- /** Convert a tile's transportation features to clipped world-metre drafts. */
179
- function featureDrafts(input, options) {
178
+ /** Whether a point belongs to a tile part: half-open, so a point on a shared border has one. */
179
+ function inPart(bounds, x, z) {
180
+ return x >= bounds[0] && x < bounds[2] && z >= bounds[1] && z < bounds[3];
181
+ }
182
+ function worldBox(points) {
183
+ const box = [
184
+ Number.POSITIVE_INFINITY,
185
+ Number.POSITIVE_INFINITY,
186
+ Number.NEGATIVE_INFINITY,
187
+ Number.NEGATIVE_INFINITY
188
+ ];
189
+ for (const [x, z] of points) {
190
+ box[0] = dmath.min(box[0], x);
191
+ box[1] = dmath.min(box[1], z);
192
+ box[2] = dmath.max(box[2], x);
193
+ box[3] = dmath.max(box[3], z);
194
+ }
195
+ return box;
196
+ }
197
+ const PART_CELLS = 16;
198
+ /**
199
+ * Joined world lines per features list: a tile registered in parts (AmbientTileInput.bounds)
200
+ * grouped and joined all its lines again for every part, most of a part's drafting time.
201
+ */
202
+ const preparedTiles = /* @__PURE__ */ new WeakMap();
203
+ function prepareTile(input, options) {
180
204
  const { origin, tileSize } = input;
181
- const minX = origin[0];
182
- const minZ = origin[1];
183
- const maxX = origin[0] + tileSize;
184
- const maxZ = origin[1] + tileSize;
185
- const drafts = [];
186
- const runways = [];
205
+ const cached = preparedTiles.get(input.features);
206
+ if (cached !== void 0 && cached.origin[0] === origin[0] && cached.origin[1] === origin[1] && cached.tileSize === tileSize && cached.tunnels === options.tunnels) return cached;
187
207
  const toWorld = (line) => line.map((p) => [origin[0] + p[0] * tileSize, origin[1] + p[1] * tileSize]);
208
+ const features = [];
209
+ const runways = [];
188
210
  for (const feature of groupTransportationFeatures(input.features)) {
189
211
  const classified = classifyFeature(feature);
190
212
  if (classified === void 0) continue;
@@ -202,28 +224,128 @@ function featureDrafts(input, options) {
202
224
  const kind = transportKind(feature);
203
225
  const width = classified.class === "water" ? feature.width ?? 60 : classified.class === "walk" ? dmath.max(1.2, feature.width ?? 2.4) : classified.class === "rail" ? 3 : transportWidth(feature, kind);
204
226
  const lanes = classified.class === "road" ? roadLanes(feature, width).total : 2;
205
- const link = isTransportLink(feature);
206
- for (const line of joinTerrainLines(feature.lines)) for (const piece of clipPolyline(toWorld(line), minX, minZ, maxX, maxZ)) {
207
- const draft = {
208
- class: classified.class,
209
- kind: classified.kind,
210
- points: piece,
211
- width,
212
- lanes,
213
- oneway: feature.oneway === true && (classified.class === "road" || classified.class === "water"),
214
- layer: feature.layer ?? 0,
215
- bridge: feature.bridge === true,
216
- tunnel: feature.tunnel === true,
217
- link,
218
- ...feature.name !== void 0 ? { name: feature.name } : {},
219
- ...feature.deckElevation !== void 0 ? { deckElevation: feature.deckElevation } : {}
220
- };
221
- if (feature.bridgeConnections !== void 0 && feature.bridgeConnections.length > 0) draft.bridgeConnections = feature.bridgeConnections.map((c) => ({
222
- point: [origin[0] + c.point[0] * tileSize, origin[1] + c.point[1] * tileSize],
223
- elevation: c.elevation,
224
- radius: c.radius
225
- }));
226
- drafts.push(draft);
227
+ const draft = {
228
+ class: classified.class,
229
+ kind: classified.kind,
230
+ width,
231
+ lanes,
232
+ oneway: feature.oneway === true && (classified.class === "road" || classified.class === "water"),
233
+ layer: feature.layer ?? 0,
234
+ bridge: feature.bridge === true,
235
+ tunnel: feature.tunnel === true,
236
+ link: isTransportLink(feature),
237
+ ...feature.name !== void 0 ? { name: feature.name } : {},
238
+ ...feature.deckElevation !== void 0 ? { deckElevation: feature.deckElevation } : {}
239
+ };
240
+ if (feature.bridgeConnections !== void 0 && feature.bridgeConnections.length > 0) draft.bridgeConnections = feature.bridgeConnections.map((c) => ({
241
+ point: [origin[0] + c.point[0] * tileSize, origin[1] + c.point[1] * tileSize],
242
+ elevation: c.elevation,
243
+ radius: c.radius
244
+ }));
245
+ if (feature.bridgeApproachProfile?.length) draft.bridgeApproachProfile = feature.bridgeApproachProfile.map((sample) => ({
246
+ ...sample,
247
+ point: [origin[0] + sample.point[0] * tileSize, origin[1] + sample.point[1] * tileSize]
248
+ }));
249
+ features.push({
250
+ draft,
251
+ source: feature
252
+ });
253
+ }
254
+ const prepared = {
255
+ origin,
256
+ tileSize,
257
+ tunnels: options.tunnels,
258
+ features,
259
+ runways
260
+ };
261
+ preparedTiles.set(input.features, prepared);
262
+ return prepared;
263
+ }
264
+ /** World bounds of each of a feature's source lines and of them all (see PreparedFeature). */
265
+ function lineBoxes(feature, origin, tileSize) {
266
+ if (feature.boxes !== void 0) return;
267
+ const source = feature.source.lines;
268
+ const boxes = new Float64Array(source.length * 4);
269
+ const all = [
270
+ Number.POSITIVE_INFINITY,
271
+ Number.POSITIVE_INFINITY,
272
+ Number.NEGATIVE_INFINITY,
273
+ Number.NEGATIVE_INFINITY
274
+ ];
275
+ source.forEach((line, i) => {
276
+ const box = worldBox(line);
277
+ boxes[i * 4] = origin[0] + box[0] * tileSize;
278
+ boxes[i * 4 + 1] = origin[1] + box[1] * tileSize;
279
+ boxes[i * 4 + 2] = origin[0] + box[2] * tileSize;
280
+ boxes[i * 4 + 3] = origin[1] + box[3] * tileSize;
281
+ all[0] = dmath.min(all[0], boxes[i * 4]);
282
+ all[1] = dmath.min(all[1], boxes[i * 4 + 1]);
283
+ all[2] = dmath.max(all[2], boxes[i * 4 + 2]);
284
+ all[3] = dmath.max(all[3], boxes[i * 4 + 3]);
285
+ });
286
+ feature.boxes = boxes;
287
+ feature.box = all;
288
+ }
289
+ /**
290
+ * The prepared features whose boxes may reach a part, in their order (every one for a whole
291
+ * tile), boxes made. Each still checks its own box against the part.
292
+ */
293
+ function partFeatures(prepared, origin, tileSize, bounds) {
294
+ const cell = (value, start) => dmath.clamp(dmath.floor((value - start) / tileSize * PART_CELLS), 0, PART_CELLS - 1);
295
+ if (bounds === void 0) {
296
+ for (const feature of prepared.features) lineBoxes(feature, origin, tileSize);
297
+ return prepared.features;
298
+ }
299
+ let cells = prepared.cells;
300
+ if (cells === void 0) {
301
+ const made = Array.from({ length: PART_CELLS * PART_CELLS }, () => []);
302
+ prepared.features.forEach((feature, index) => {
303
+ lineBoxes(feature, origin, tileSize);
304
+ const [x0, z0, x1, z1] = feature.box;
305
+ for (let row = cell(z0, origin[1]); row <= cell(z1, origin[1]); row++) for (let col = cell(x0, origin[0]); col <= cell(x1, origin[0]); col++) made[row * PART_CELLS + col].push(index);
306
+ });
307
+ prepared.cells = made;
308
+ cells = made;
309
+ }
310
+ const picked = /* @__PURE__ */ new Set();
311
+ for (let row = cell(bounds[1], origin[1]); row <= cell(bounds[3], origin[1]); row++) for (let col = cell(bounds[0], origin[0]); col <= cell(bounds[2], origin[0]); col++) for (const index of cells[row * PART_CELLS + col]) picked.add(index);
312
+ return [...picked].sort((a, b) => a - b).map((index) => prepared.features[index]);
313
+ }
314
+ /** Convert a tile's transportation features to clipped world-metre drafts. */
315
+ function featureDrafts(input, options) {
316
+ const { origin, tileSize, bounds } = input;
317
+ const minX = bounds?.[0] ?? origin[0];
318
+ const minZ = bounds?.[1] ?? origin[1];
319
+ const maxX = bounds?.[2] ?? origin[0] + tileSize;
320
+ const maxZ = bounds?.[3] ?? origin[1] + tileSize;
321
+ const prepared = prepareTile(input, options);
322
+ const drafts = [];
323
+ const runways = prepared.runways.filter(({ a, b }) => !bounds || inPart(bounds, (a[0] + b[0]) / 2, (a[1] + b[1]) / 2)).map(({ a, b }) => ({
324
+ a: [a[0], a[1]],
325
+ b: [b[0], b[1]]
326
+ }));
327
+ for (const feature of partFeatures(prepared, origin, tileSize, bounds)) {
328
+ const source = feature.source.lines;
329
+ const reach = feature.box;
330
+ if (reach[2] < minX || reach[0] > maxX || reach[3] < minZ || reach[1] > maxZ) continue;
331
+ const boxes = feature.boxes;
332
+ const reaching = source.filter((_, i) => !(boxes[i * 4 + 2] < minX || boxes[i * 4] > maxX || boxes[i * 4 + 3] < minZ || boxes[i * 4 + 1] > maxZ));
333
+ if (!reaching.length) continue;
334
+ const draft = feature.draft;
335
+ for (const line of joinTerrainLines(reaching, feature.source.oneway === true)) {
336
+ const points = line.map((p) => [origin[0] + p[0] * tileSize, origin[1] + p[1] * tileSize]);
337
+ for (const piece of clipPolyline(points, minX, minZ, maxX, maxZ)) drafts.push({
338
+ ...draft,
339
+ points: piece.map((p) => [p[0], p[1]]),
340
+ ...draft.bridgeConnections !== void 0 ? { bridgeConnections: draft.bridgeConnections.map((c) => ({
341
+ ...c,
342
+ point: [c.point[0], c.point[1]]
343
+ })) } : {},
344
+ ...draft.bridgeApproachProfile !== void 0 ? { bridgeApproachProfile: draft.bridgeApproachProfile.map((sample) => ({
345
+ ...sample,
346
+ point: [sample.point[0], sample.point[1]]
347
+ })) } : {}
348
+ });
227
349
  }
228
350
  }
229
351
  return {
@@ -237,25 +359,51 @@ const POI_KINDS = new Set([
237
359
  "tram_stop",
238
360
  "bus_stop",
239
361
  "traffic_signals",
362
+ "give_way",
363
+ "stop",
240
364
  "crossing",
241
365
  "aerodrome"
242
366
  ]);
243
367
  /** Convert a tile's POIs to world points (only those inside the tile). */
244
- function tilePois(pois, origin, tileSize) {
245
- const result = [];
246
- for (const poi of pois ?? []) {
247
- const kind = (poi.subclass ?? poi.class).toLowerCase();
248
- const matched = POI_KINDS.has(kind) ? kind : POI_KINDS.has(poi.class) ? poi.class : void 0;
249
- if (matched === void 0) continue;
250
- const [u, v] = poi.point;
251
- if (u < 0 || u > 1 || v < 0 || v > 1) continue;
252
- result.push({
253
- kind: matched,
254
- x: origin[0] + u * tileSize,
255
- z: origin[1] + v * tileSize,
256
- ...poi.name !== void 0 ? { name: poi.name } : {}
257
- });
368
+ /**
369
+ * A tile's POIs matched and placed once: a tile registered in parts read and matched every one of
370
+ * them again for each part.
371
+ */
372
+ const placedPois = /* @__PURE__ */ new WeakMap();
373
+ function tilePois(pois, origin, tileSize, bounds) {
374
+ if (pois === void 0) return [];
375
+ let placed = placedPois.get(pois);
376
+ if (placed === void 0 || placed.origin[0] !== origin[0] || placed.origin[1] !== origin[1] || placed.tileSize !== tileSize) {
377
+ const all = [];
378
+ for (const poi of pois) {
379
+ const kind = (poi.subclass ?? poi.class).toLowerCase();
380
+ const matched = POI_KINDS.has(kind) ? kind : POI_KINDS.has(poi.class) ? poi.class : void 0;
381
+ if (matched === void 0) continue;
382
+ if ([
383
+ "traffic_signals",
384
+ "stop",
385
+ "give_way"
386
+ ].includes(matched) && (poi.bridge || poi.tunnel)) continue;
387
+ const [u, v] = poi.point;
388
+ if (u < 0 || u > 1 || v < 0 || v > 1) continue;
389
+ all.push({
390
+ kind: matched === "stop" ? "give_way" : matched,
391
+ x: origin[0] + u * tileSize,
392
+ z: origin[1] + v * tileSize,
393
+ ...poi.name !== void 0 ? { name: poi.name } : {},
394
+ ...poi.stop === "all" ? { allWay: true } : {},
395
+ layer: poi.layer ?? 0
396
+ });
397
+ }
398
+ placed = {
399
+ origin: [origin[0], origin[1]],
400
+ tileSize,
401
+ pois: all
402
+ };
403
+ placedPois.set(pois, placed);
258
404
  }
405
+ const result = [];
406
+ for (const poi of placed.pois) if (!bounds || inPart(bounds, poi.x, poi.z)) result.push({ ...poi });
259
407
  return result;
260
408
  }
261
409
  //#endregion
@@ -288,6 +436,7 @@ function wayDraft(way) {
288
436
  const points = way.points.map((p) => p.length === 3 ? [p[0], p[2]] : [p[0], p[1]]);
289
437
  const heights = way.points.every((p) => p.length === 3) ? way.points.map((p) => p[1]) : void 0;
290
438
  const common = {
439
+ ...way.drivingSide !== void 0 ? { drivingSide: way.drivingSide } : {},
291
440
  points,
292
441
  ...heights !== void 0 ? { heights } : {},
293
442
  layer: way.layer ?? 0,
@@ -436,6 +585,7 @@ const ambientAgentSchema = z.strictObject({
436
585
  lane: z.string().describe("Lane id the agent is on (\"\" for aircraft)."),
437
586
  s: num.describe("Metres along the lane; negative while on the connector into it."),
438
587
  speed: num.nonnegative().describe("Speed along the lane in m/s."),
588
+ boosted: z.boolean().optional().describe("Lane speed includes the 4× travel boost."),
439
589
  cruise: num.positive().describe("Vessel cruise limit in m/s.").optional(),
440
590
  prev: z.string().describe("Previous lane (its connector leads onto `lane`).").optional(),
441
591
  next: z.string().describe("Chosen next lane.").optional(),
@@ -513,6 +663,7 @@ const ambientStateSchema = z.strictObject({
513
663
  });
514
664
  const point = z.union([vec2, vec3]);
515
665
  const waySchema = z.strictObject({
666
+ drivingSide: z.enum(["right", "left"]).describe("Overrides the document road driving side.").optional(),
516
667
  id: z.string().min(1).describe("Optional stable id.").optional(),
517
668
  class: z.enum([
518
669
  "road",
package/dist/kernel.d.mts CHANGED
@@ -1,7 +1,8 @@
1
- import { a as WildlifeWorld, c as WILDLIFE_FAMILIES, d as WildlifeHabitat, f as WildlifeMotion, i as WildlifeBudget, l as WildlifeChoice, m as wildlifeSpeciesSchema, n as WILDLIFE_TICK_RATE, o as stepWildlife, p as WildlifeSpecies, r as WildlifeAgent, s as wildlifeCandidates, t as WILDLIFE_CELL_METERS, u as WildlifeFamily } from "./wildlife-B4EL0z-N.mjs";
1
+ import { a as WildlifeWorld, c as WILDLIFE_FAMILIES, d as WildlifeHabitat, f as WildlifeMotion, i as WildlifeBudget, l as WildlifeChoice, m as wildlifeSpeciesSchema, n as WILDLIFE_TICK_RATE, o as stepWildlife, p as WildlifeSpecies, r as WildlifeAgent, s as wildlifeCandidates, t as WILDLIFE_CELL_METERS, u as WildlifeFamily } from "./wildlife-CvHzzI9m.mjs";
2
2
  import { Quat } from "@bendyline/molen-kernel/determinism";
3
3
  import { ComponentType, JsonObject, World } from "@bendyline/molen-kernel/world";
4
4
  import { ComponentMap, EntityId, SceneManifest } from "@bendyline/molen-schema";
5
+ import { z } from "zod";
5
6
  import { TerrainLinePath, TerrainPoiFeature, TerrainTransportationFeature } from "@bendyline/molen-terrain/kernel";
6
7
 
7
8
  //#region src/kernel/components.d.ts
@@ -19,6 +20,8 @@ interface AmbientAirCorridor extends JsonObject {
19
20
  length: number;
20
21
  }
21
22
  interface AmbientAgentData extends JsonObject {
23
+ /** Kernel-owned: the lane speed includes the world's 4× travel boost. */
24
+ boosted?: boolean;
22
25
  kind: AmbientKind;
23
26
  type: string;
24
27
  color?: string;
@@ -205,6 +208,8 @@ interface TransportEdge {
205
208
  readonly tunnel: boolean;
206
209
  readonly link: boolean;
207
210
  readonly oneway: boolean;
211
+ /** Regional road traffic rule, retained through junction rebuilds and export. */
212
+ readonly drivingSide: "right" | "left";
208
213
  readonly lanes: string[];
209
214
  /** Source feature name, when mapped. */
210
215
  readonly name?: string;
@@ -216,7 +221,7 @@ interface TransportLane {
216
221
  readonly class: TransportClass;
217
222
  /** 1 travels the edge path forward (from → to), -1 backward. */
218
223
  readonly dir: 1 | -1;
219
- /** 0 = innermost (nearest the centreline for two-way roads, leftmost for one-way). */
224
+ /** 0 = innermost (leftmost for right-hand one-way roads, rightmost for left-hand). */
220
225
  readonly index: number;
221
226
  /** Signed lateral offset from the centreline, positive to the right of travel. */
222
227
  readonly offset: number;
@@ -340,6 +345,7 @@ declare function allRed(junction: TransportJunction, tick: number, tickRate: num
340
345
  type Point2 = [number, number];
341
346
  /** A polyline awaiting the planar split, in world metres. */
342
347
  interface EdgeDraft {
348
+ drivingSide?: "right" | "left";
343
349
  class: TransportClass;
344
350
  kind: RoadKind;
345
351
  points: Point2[];
@@ -361,6 +367,11 @@ interface EdgeDraft {
361
367
  elevation: number;
362
368
  radius: number;
363
369
  }[];
370
+ bridgeApproachProfile?: {
371
+ point: Point2;
372
+ elevation: number;
373
+ flatness: number;
374
+ }[];
364
375
  }
365
376
  /** Design speeds in m/s by kind. */
366
377
  declare const KIND_SPEED: Readonly<Record<RoadKind, number>>;
@@ -382,6 +393,8 @@ interface TileDraftInput {
382
393
  origin: readonly [number, number];
383
394
  tileSize: number;
384
395
  features: readonly TerrainTransportationFeature[];
396
+ /** World X/Z part of the tile to keep (see AmbientTileInput.bounds); default the whole tile. */
397
+ bounds?: readonly [number, number, number, number];
385
398
  }
386
399
  interface TileDrafts {
387
400
  drafts: EdgeDraft[];
@@ -400,6 +413,8 @@ interface WorldPoi {
400
413
  name?: string;
401
414
  /** Stations: dwell time in seconds. */
402
415
  dwell?: number;
416
+ allWay?: boolean;
417
+ layer?: number;
403
418
  }
404
419
  //#endregion
405
420
  //#region src/kernel/graph/doc.d.ts
@@ -407,6 +422,8 @@ declare const TRANSPORT_NETWORK_FORMAT: "molen/transport-network@1";
407
422
  /** A way's point: `[x, z]` or `[x, y, z]` in scene metres. */
408
423
  type TransportNetworkPoint = [number, number] | [number, number, number];
409
424
  interface TransportNetworkWay {
425
+ /** Overrides the document's road driving side. */
426
+ drivingSide?: "right" | "left";
410
427
  id?: string;
411
428
  class: "road" | "rail" | "path" | "air" | "water";
412
429
  subclass?: string;
@@ -469,11 +486,12 @@ interface GraphStore {
469
486
  setJunction(junction: TransportJunction): void;
470
487
  deleteJunction(id: string): void;
471
488
  /** Whether a mapped traffic-signal point lies within `radius` of a point. */
472
- signalNear(x: number, z: number, radius: number): boolean;
489
+ signalNear(x: number, z: number, radius: number, layer?: number): boolean;
473
490
  /** Stop and yield signs within `radius` of a point. */
474
- giveWayNear(x: number, z: number, radius: number): readonly {
491
+ giveWayNear(x: number, z: number, radius: number, layer?: number): readonly {
475
492
  x: number;
476
493
  z: number;
494
+ allWay?: boolean;
477
495
  }[];
478
496
  }
479
497
  /** Monotone stand-in for atan2 in [0, 4): orders directions without transcendental math. */
@@ -483,6 +501,12 @@ declare function pseudoAngle(dx: number, dz: number): number;
483
501
  declare const GRID_CELL = 64;
484
502
  interface EdgeSpan {
485
503
  readonly edge: string;
504
+ /**
505
+ * The edge itself and its lanes of each class, as inserted: a spawner weighs every span within
506
+ * reach, and looking both up by id for each was most of a run's few milliseconds.
507
+ */
508
+ readonly ref: TransportEdge;
509
+ readonly lanes: Readonly<Record<TransportClass, number>>;
486
510
  /** Edge-path distances bounding the span. */
487
511
  readonly d0: number;
488
512
  readonly d1: number;
@@ -491,13 +515,26 @@ interface EdgeSpan {
491
515
  readonly z: number;
492
516
  }
493
517
  declare class LaneGrid {
494
- private readonly cells;
518
+ /** Rows by cell z, then cells by cell x: integer keys, no string per probed cell. */
519
+ private readonly rows;
520
+ private cellCount;
495
521
  private readonly edgeCells;
496
522
  /** Bumped on every change; lets callers cache derived sums. */
497
523
  version: number;
498
524
  insert(edge: TransportEdge, laneCounts: Readonly<Record<TransportClass, number>>): void;
499
525
  remove(edgeId: string): void;
500
- /** Visit cells overlapping the disc of radius `r`, in a deterministic order. */
526
+ /**
527
+ * Remove edges together, each touched cell's spans filtered once: a tile's edges share its
528
+ * cells, and filtering a dense city cell again for each of its edges held a frame 5 ms as the
529
+ * tile left.
530
+ */
531
+ removeAll(edgeIds: Iterable<string>): void;
532
+ /**
533
+ * Cells overlapping the disc of radius `r`, in row-major order (z, then x, ascending). A train
534
+ * or boat ring spans thousands of mostly empty cells: probing each one cost a fast flight
535
+ * several milliseconds per spawner run, so a disc larger than the populated grid walks the
536
+ * populated cells instead and sorts the matches into the same order.
537
+ */
501
538
  private cellsNear;
502
539
  /** Lane-metres of a class in cells overlapping the disc. */
503
540
  laneMeters(x: number, z: number, r: number, cls: TransportClass): number;
@@ -511,6 +548,8 @@ declare class LaneGrid {
511
548
  //#region src/kernel/graph/network.d.ts
512
549
  /** One streamed map tile's transport data. */
513
550
  interface AmbientTileInput {
551
+ /** Regional road driving side; defaults to the network's traffic setting. */
552
+ drivingSide?: "right" | "left";
514
553
  /** Unique tile key, e.g. `terrainPyramidTileKey(address)`. */
515
554
  key: string;
516
555
  /** World X/Z of the tile's north-west corner, in metres. */
@@ -523,6 +562,12 @@ interface AmbientTileInput {
523
562
  heightAt?: (x: number, z: number) => number;
524
563
  /** Infer sidewalks along streets without mapped footways (default true). */
525
564
  sidewalks?: boolean;
565
+ /**
566
+ * Build only this world X/Z part of the tile, [minX, minZ, maxX, maxZ] (default: all of it).
567
+ * A large tile registered as parts, each under its own key, costs a tick a part instead of
568
+ * one long tick; edges stitch across part borders as across tile borders.
569
+ */
570
+ bounds?: readonly [number, number, number, number];
526
571
  }
527
572
  interface TransportNetworkOptions {
528
573
  traffic?: "right" | "left";
@@ -545,6 +590,7 @@ interface TransportNetworkStats {
545
590
  }
546
591
  /** A script-added polyline. */
547
592
  interface AmbientPolyline {
593
+ drivingSide?: "right" | "left";
548
594
  class: "road" | "rail" | "path" | "water";
549
595
  subclass?: string;
550
596
  /** `[x, z]` or `[x, y, z]` points in scene metres. */
@@ -564,8 +610,14 @@ declare class TransportNetwork implements GraphStore {
564
610
  private readonly nodes;
565
611
  private readonly edges;
566
612
  private readonly lanes;
613
+ /** Each edge's lane count per class (see lanesOfClass), kept with its lanes. */
614
+ private readonly classLanes;
567
615
  private readonly junctions;
568
616
  private readonly tiles;
617
+ /**
618
+ * Border nodes by class and layer, then by rounded position (see borderCell): stitching probes
619
+ * the 25 positions around each new border node, and a string key for each was most of it.
620
+ */
569
621
  private readonly borders;
570
622
  private readonly crossings;
571
623
  private readonly crossingsByEdge;
@@ -584,11 +636,16 @@ declare class TransportNetwork implements GraphStore {
584
636
  node(id: string): TransportNode | undefined;
585
637
  edge(id: string): TransportEdge | undefined;
586
638
  lane(id: string): TransportLane | undefined;
639
+ /**
640
+ * How many of an edge's lanes are of `cls`. A city's spawn ring is tens of thousands of spans,
641
+ * and looking up every lane of each one held a spawning tick near 10 ms.
642
+ */
643
+ lanesOfClass(edgeId: string, cls: TransportClass): number;
587
644
  junction(id: string): TransportJunction | undefined;
588
645
  setJunction(junction: TransportJunction): void;
589
646
  deleteJunction(id: string): void;
590
- signalNear(x: number, z: number, radius: number): boolean;
591
- giveWayNear(x: number, z: number, radius: number): readonly WorldPoi[];
647
+ signalNear(x: number, z: number, radius: number, layer?: number): boolean;
648
+ giveWayNear(x: number, z: number, radius: number, layer?: number): readonly WorldPoi[];
592
649
  private controlsNear;
593
650
  /** Whether a tile key is registered. */
594
651
  hasTile(key: string): boolean;
@@ -631,6 +688,8 @@ declare class TransportNetwork implements GraphStore {
631
688
  s: number;
632
689
  distance: number;
633
690
  } | undefined;
691
+ /** The network's sizes, without the walks `stats()` makes. */
692
+ sizes(): Pick<TransportNetworkStats, "tiles" | "nodes" | "edges" | "lanes" | "junctions">;
634
693
  stats(): TransportNetworkStats;
635
694
  /** Drop everything. */
636
695
  clear(): void;
@@ -646,6 +705,8 @@ interface AmbientSolid {
646
705
  radius: number;
647
706
  }
648
707
  interface AgentEnv {
708
+ /** Internal scale resolved from the world's boost setting by stepAgents. */
709
+ speedScale?: number;
649
710
  net: TransportNetwork;
650
711
  policy: AmbientPolicy;
651
712
  tick: number;
@@ -661,7 +722,7 @@ declare function agentSample(net: TransportNetwork, agent: Readonly<AmbientAgent
661
722
  /** Rotation for an agent facing along a sample (with pitch unless flat). */
662
723
  declare function agentRotation(sample: LaneSample, pitch: boolean): Quat;
663
724
  /** Advance every ambient agent one tick. */
664
- declare function stepAgents(world: World, env: AgentEnv): void;
725
+ declare function stepAgents(world: World, environment: AgentEnv): void;
665
726
  /** Step back `distance` metres from a lane position along the lead's trail. */
666
727
  declare function walkBack(net: TransportNetwork, laneId: string, s: number, prev: string | undefined, trail: readonly string[], distance: number): {
667
728
  lane: string;
@@ -734,12 +795,26 @@ interface AmbientOptions {
734
795
  policy?: DeepPartial<AmbientPolicy>;
735
796
  /** Vehicle and pedestrian types per class (default: proxy dimensions). */
736
797
  types?: Partial<AmbientTypes>;
798
+ /** Deterministic local road fleet at a prospective spawn point. An empty list suppresses it. */
799
+ carsAt?: (x: number, z: number) => readonly AmbientVehicleType[];
737
800
  /** Extra components per class; `null` spawns bare agents (ambientAgent + transform only). */
738
801
  templates?: Partial<Record<AmbientKind, AmbientTemplate | null>>;
739
802
  /** Seed for spawn draws (default: 'ambient'). */
740
803
  seed?: string | number;
741
804
  /** Cars yield to vehicles someone is driving (`mounted` riders); default true. */
742
805
  yieldToDriven?: boolean;
806
+ /**
807
+ * Tile registrations a tick applies, in queue order (removals are not counted); default all.
808
+ * A dense tile's network takes tens of milliseconds to build, so a host streaming many tiles
809
+ * (or one tile in parts, see AmbientTileInput.bounds) passes 1 to keep each tick short.
810
+ */
811
+ registrationsPerTick?: number;
812
+ /**
813
+ * Tile removals a tick applies, in queue order; default all. A tile streamed in parts leaves
814
+ * all at once, and removing every part (rebuilding the junctions they were stitched to) in one
815
+ * tick held it 10 ms.
816
+ */
817
+ removalsPerTick?: number;
743
818
  }
744
819
  interface AmbientStats {
745
820
  network: TransportNetworkStats;
@@ -760,7 +835,7 @@ interface AmbientBox {
760
835
  interface AmbientHandle {
761
836
  readonly world: World;
762
837
  readonly network: TransportNetwork;
763
- /** Queue a streamed tile (applied at the next tick, or by `flush()`). */
838
+ /** Queue a streamed tile (applied at a coming tick, see registrationsPerTick, or by `flush()`). */
764
839
  registerTile(tile: AmbientTileInput): void;
765
840
  unregisterTile(key: string): void;
766
841
  /** Apply queued tile changes now (outside a tick). */
@@ -809,6 +884,34 @@ interface AmbientCapabilityOptions extends Omit<AmbientOptions, "classes" | "see
809
884
  /** Build-world capability hook: `buildWorld(scene, setup, { capabilities: [ambientCapability()] })`. */
810
885
  declare function ambientCapability(opts?: AmbientCapabilityOptions): (world: World, manifest: SceneManifest) => Record<string, object> | undefined;
811
886
  //#endregion
887
+ //#region src/kernel/fleet.d.ts
888
+ interface FleetCatalog {
889
+ format: "molen/fleet-catalog@1";
890
+ id: string;
891
+ version: number;
892
+ description: string;
893
+ fallback: string;
894
+ regions: Record<string, string>;
895
+ profiles: Array<{
896
+ id: string;
897
+ title: string;
898
+ extends?: string;
899
+ weights: Record<string, number>;
900
+ }>;
901
+ }
902
+ declare const fleetCatalogSchema: z.ZodType<FleetCatalog>;
903
+ interface FleetMix {
904
+ profile: string;
905
+ weights: ReadonlyMap<string, number>;
906
+ }
907
+ interface FleetLibrary {
908
+ regions: ReadonlyMap<string, string>;
909
+ /** Stable bounded shortlist; never depends on camera motion, downloads or wall time. */
910
+ select(region?: string): FleetMix;
911
+ }
912
+ declare function createFleetLibrary(documents: readonly FleetCatalog[], available: ReadonlySet<string>, maxModels?: number): FleetLibrary;
913
+ declare function registerFleetSchema(): void;
914
+ //#endregion
812
915
  //#region src/kernel/graph/export.d.ts
813
916
  /** Every road, rail and path edge as a way (with surface heights), plus stations and signals. */
814
917
  declare function networkToDocument(network: TransportNetwork, meta?: Pick<TransportNetworkDocument, "name" | "origin">, options?: {
@@ -893,4 +996,4 @@ interface ObserverView {
893
996
  keep?: number;
894
997
  }
895
998
  //#endregion
896
- export { AMBIENT_AGENT_COMPONENT, AMBIENT_ENTITY, AMBIENT_KINDS, AMBIENT_OBSERVER_COMPONENT, AMBIENT_ROLE_COMPONENT, AMBIENT_STATE_COMPONENT, type AgentEnv, AmbientAgent, type AmbientAgentData, type AmbientAirCorridor, type AmbientBox, type AmbientBudget, type AmbientCapabilityOptions, type AmbientClassPolicy, type AmbientHandle, type AmbientKind, AmbientObserver, type AmbientObserverData, type AmbientObserverState, type AmbientOptions, type AmbientPedestrianType, type AmbientPolicy, type AmbientPolyline, AmbientRole, type AmbientRoleData, type AmbientRoleVisual, type AmbientSolid, type AmbientSpawnInfo, AmbientState, type AmbientStateData, type AmbientStats, type AmbientTemplate, type AmbientTileInput, type AmbientTypes, type AmbientVehicleType, CAR_COLORS, DEFAULT_POLICY, DEFAULT_TEMPLATES, DEFAULT_TYPES, type DeepPartial, type DriverParams, type EdgeDraft, type EdgeSpan, GRID_CELL, type JunctionArm, type JunctionControl, KIND_SPEED, LaneGrid, type LaneMovement, type LaneSample, type LaneStop, type ObserverView, type PlanarNode, type PlanarPiece, type PlanarResult, type RoadKind, type SignalColor, type SignalTiming, TRANSPORT_NETWORK_EXAMPLE, TRANSPORT_NETWORK_FORMAT, type TransportClass, type TransportCrossing, type TransportEdge, type TransportJunction, type TransportLane, TransportNetwork, type TransportNetworkAerodrome, type TransportNetworkDocument, type TransportNetworkOptions, type TransportNetworkPoint, type TransportNetworkSignal, type TransportNetworkStation, type TransportNetworkStats, type TransportNetworkWay, type TransportNode, type TransportRunway, type TurnKind, WILDLIFE_CELL_METERS, WILDLIFE_FAMILIES, WILDLIFE_TICK_RATE, type WildlifeAgent, type WildlifeBudget, type WildlifeChoice, type WildlifeFamily, type WildlifeHabitat, type WildlifeMotion, type WildlifeSpecies, type WildlifeWorld, type WorldPoi, agentRotation, agentSample, allRed, ambientCapability, ambientOf, ambientScriptApi, chooseNext, classifyFeature, clipPolyline, edgeHeight, featureDrafts, fmix32, idmAcceleration, installAmbient, laneCoordinate, laneEdgeDistance, laneSample, mergePolicy, networkToDocument, pickWeighted, planarSplit, policyForBudget, pseudoAngle, registerAmbientSchema, sampleConnector, sampleLaneBody, signalColor, signalTiming, stepAgents, stepWildlife, stoppingDistance, unit01, walkBack, wildlifeCandidates, wildlifeSpeciesSchema };
999
+ export { AMBIENT_AGENT_COMPONENT, AMBIENT_ENTITY, AMBIENT_KINDS, AMBIENT_OBSERVER_COMPONENT, AMBIENT_ROLE_COMPONENT, AMBIENT_STATE_COMPONENT, type AgentEnv, AmbientAgent, type AmbientAgentData, type AmbientAirCorridor, type AmbientBox, type AmbientBudget, type AmbientCapabilityOptions, type AmbientClassPolicy, type AmbientHandle, type AmbientKind, AmbientObserver, type AmbientObserverData, type AmbientObserverState, type AmbientOptions, type AmbientPedestrianType, type AmbientPolicy, type AmbientPolyline, AmbientRole, type AmbientRoleData, type AmbientRoleVisual, type AmbientSolid, type AmbientSpawnInfo, AmbientState, type AmbientStateData, type AmbientStats, type AmbientTemplate, type AmbientTileInput, type AmbientTypes, type AmbientVehicleType, CAR_COLORS, DEFAULT_POLICY, DEFAULT_TEMPLATES, DEFAULT_TYPES, type DeepPartial, type DriverParams, type EdgeDraft, type EdgeSpan, type FleetCatalog, type FleetLibrary, type FleetMix, GRID_CELL, type JunctionArm, type JunctionControl, KIND_SPEED, LaneGrid, type LaneMovement, type LaneSample, type LaneStop, type ObserverView, type PlanarNode, type PlanarPiece, type PlanarResult, type RoadKind, type SignalColor, type SignalTiming, TRANSPORT_NETWORK_EXAMPLE, TRANSPORT_NETWORK_FORMAT, type TransportClass, type TransportCrossing, type TransportEdge, type TransportJunction, type TransportLane, TransportNetwork, type TransportNetworkAerodrome, type TransportNetworkDocument, type TransportNetworkOptions, type TransportNetworkPoint, type TransportNetworkSignal, type TransportNetworkStation, type TransportNetworkStats, type TransportNetworkWay, type TransportNode, type TransportRunway, type TurnKind, WILDLIFE_CELL_METERS, WILDLIFE_FAMILIES, WILDLIFE_TICK_RATE, type WildlifeAgent, type WildlifeBudget, type WildlifeChoice, type WildlifeFamily, type WildlifeHabitat, type WildlifeMotion, type WildlifeSpecies, type WildlifeWorld, type WorldPoi, agentRotation, agentSample, allRed, ambientCapability, ambientOf, ambientScriptApi, chooseNext, classifyFeature, clipPolyline, createFleetLibrary, edgeHeight, featureDrafts, fleetCatalogSchema, fmix32, idmAcceleration, installAmbient, laneCoordinate, laneEdgeDistance, laneSample, mergePolicy, networkToDocument, pickWeighted, planarSplit, policyForBudget, pseudoAngle, registerAmbientSchema, registerFleetSchema, sampleConnector, sampleLaneBody, signalColor, signalTiming, stepAgents, stepWildlife, stoppingDistance, unit01, walkBack, wildlifeCandidates, wildlifeSpeciesSchema };