@adatechnology/game-urban 0.2.8 → 0.3.1

package/README.md

@@ -75,8 +75,8 @@ const plan = urban.neighbourhoods.get('suburb').compose(b, { x: 0, z: 0 }, {
   locale: 'en',
   providers: {
     house: (typology, request, b) => myHouse(typology, request, b),   // default: the far-away silhouettes of game-floorplan
-    vehicle: createVehicleProvider(),                                // default: none (the page's box car is not shipped)
-    plant: createPlantProvider(),                                    // default: the cone pine and the ball tree of the props
+    vehicle: createVehicleProvider({ ids: myFleetIds }),            // default: none (the page's box car is not shipped)
+    plant: createPlantProvider({ pickSpecies: myPicker }),          // default: the cone pine and the ball tree of the props
   },
 })
 // plan: { id, origin, houses, buildings, poles, vehicles, plants }  (what was put where)
@@ -85,7 +85,7 @@ urban.neighbourhoods.composeSampleSheet(b)   // the ground and the ten cells, in
 
 ### Vehicles and plants from the other packages
 
-`createVehicleProvider({ ids?, pick?, paint? })` parks a vehicle of `game-vehicles-fleet` (cars, SUVs, pickups and vans by default) where a pattern parks one, and `createPlantProvider({ region?, contexts?, seed?, pick? })` plants a species of `game-vegetation-species` where a pattern plants (a tree from the region's `sidewalk_tree` table, a pine from `square`). They do not draw: they add a `placement` part (`b.place(kind, id, x, z, { ry, scale, color, seed })`) that says what to put and where. The choice depends on the spot and not on `b.random`, so the scene around it keeps the same draw order. The drawer (`game-urban-three`) asks a resolver for each kind and leaves the spot empty when it has none.
+`createVehicleProvider({ ids, pick?, paint? })` parks a vehicle of the fleet the game names in `ids` where a pattern parks one, and `createPlantProvider({ pickSpecies, contexts?, seed?, pick? })` plants the species `pickSpecies(context, key)` returns where a pattern plants (a tree from the `sidewalk_tree` context, a pine from `square`). The fleet and the species come by option (the recommended path; the preset `defaultUrbanProviders()` of `@adatechnology/game-kit-defaults` uses it). Without them the providers keep the old defaults, `PARKED_VEHICLE_IDS` of `game-vehicles-fleet` and the regional tables of `game-vegetation-species`; those defaults are deprecated and removed in the next major. They do not draw: they add a `placement` part (`b.place(kind, id, x, z, { ry, scale, color, seed })`) that says what to put and where. The choice depends on the spot and not on `b.random`, so the scene around it keeps the same draw order. The drawer (`game-urban-three`) asks a resolver for each kind and leaves the spot empty when it has none.
 
 ## City plans (zoning)
 

package/dist/index.d.ts

@@ -325,16 +325,23 @@ type UrbanScene = {
         dark: SilhouetteWindow[];
     };
 };
-/** The lights a scene may spend. Every lamp that is on takes one, and the first ones win; the rest keep only their glowing lens. */
-type LightBudget = {
+/**
+ * How many lights a scene may spend (a counter, not the render budget of `@adatechnology/game-render-three`). Every lamp that is on takes one, and the first ones win; the rest keep only their
+ * glowing lens.
+ */
+type LightAllowance = {
     /** Lights left. It goes below zero when more lamps ask than the budget had, as the team's counter does. */
     left: number;
     /** True while the budget lasts (spends one either way). */
     take(): boolean;
 };
+/** @deprecated Renamed `LightAllowance`: `LightBudget` is the name of the render budget of `@adatechnology/game-render-three`. Removed in the next major. */
+type LightBudget = LightAllowance;
 
-/** The team's counter: `take()` is `left-- > 0`, so the count keeps falling after the budget is spent. */
-declare function createLightBudget(count: number): LightBudget;
+/** The team's counter: `take()` is `left-- > 0`, so the count keeps falling after the allowance is spent. */
+declare function createLightAllowance(count: number): LightAllowance;
+/** @deprecated Renamed `createLightAllowance`: `LightBudget` is the name of the render budget of `@adatechnology/game-render-three`. Removed in the next major. */
+declare const createLightBudget: typeof createLightAllowance;
 
 type BoxOptions = {
     parent?: number;
@@ -345,7 +352,7 @@ type BoxOptions = {
 };
 type UrbanBuilderOptions = {
     /** Lights the scene may spend; omitted means no limit. */
-    budget?: LightBudget;
+    budget?: LightAllowance;
 };
 /**
  * Collects the parts of an urban scene the way the team's page adds them to its root: every helper appends in call order, so a
@@ -355,7 +362,7 @@ type UrbanBuilderOptions = {
 declare function createUrbanBuilder(random: RandomSource, options?: UrbanBuilderOptions): {
     random: RandomSource;
     pick: <TEntry>(list: readonly TEntry[]) => TEntry;
-    lights: LightBudget;
+    lights: LightAllowance;
     parts: UrbanPart[];
     items: ItemBox[];
     windows: {
@@ -532,7 +539,10 @@ type PoleOptions = {
     /** Adds the transformer drum (single arm). */
     transformer?: boolean;
 };
-type PoleShapeBuilder = (b: UrbanBuilder, spec: any, o: PoleOptions) => void;
+/** Draws a pole from its `spec`. Declared as a method so the registry can hold each builder with its own spec type (the `PoleDef` names the builder that reads its spec). */
+type PoleShapeBuilder<TSpec extends object = object> = {
+    build(b: UrbanBuilder, spec: TSpec, o: PoleOptions): void;
+}['build'];
 type PoleDef = {
     id: string;
     /** Key of the shape builder that reads `spec`. */
@@ -919,7 +929,13 @@ type ComposeContext<TParams = Record<string, unknown>> = {
         shop?: number;
     }): void;
 };
-type Composer<TParams = any> = (context: ComposeContext<TParams>) => void;
+/**
+ * Draws a pattern from its params. Declared as a method so a registry of composers can hold each with its own params type
+ * (the pattern that names the composer carries the matching params).
+ */
+type Composer<TParams = Record<string, unknown>> = {
+    compose(context: ComposeContext<TParams>): void;
+}['compose'];
 type ComposeOptions = {
     locale?: Locale;
     providers?: Providers;
@@ -1127,9 +1143,9 @@ type Origin = {
     z: number;
 };
 /** Draws one pattern at `origin`: its composer, then the board with the title and the caption. */
-declare function composePattern(kit: UrbanKitCore, pattern: NeighbourhoodPattern<any>, composer: Composer, b: UrbanBuilder, origin: Origin, options?: ComposeOptions): UrbanPlan;
+declare function composePattern(kit: UrbanKitCore, pattern: NeighbourhoodPattern, composer: Composer, b: UrbanBuilder, origin: Origin, options?: ComposeOptions): UrbanPlan;
 /** The marker (map pin) of a pattern at an origin: where it stands, how high, and what it says. */
-declare function patternMarker(pattern: NeighbourhoodPattern<any>, origin: Origin, locale?: Locale): {
+declare function patternMarker(pattern: NeighbourhoodPattern, origin: Origin, locale?: Locale): {
     x: number;
     y: number;
     z: number;
@@ -1180,6 +1196,8 @@ type Terrain = ReturnType<typeof createTerrain>;
 declare function drawTerrain(b: UrbanBuilder, terrain: Terrain, segments?: number): void;
 
 /** Lights a scene may spend: the Galeria spends 16 real point lights. */
+declare const DEFAULT_LIGHT_ALLOWANCE = 16;
+/** @deprecated Renamed `DEFAULT_LIGHT_ALLOWANCE`. Removed in the next major. */
 declare const DEFAULT_LIGHT_BUDGET = 16;
 /** Seed of the Galeria's generator. */
 declare const DEFAULT_URBAN_SEED = 7;
@@ -1187,14 +1205,14 @@ type UrbanOptions = {
     /** Entries added to the catalogues (an entry with an existing id replaces it). */
     packs?: {
         poles?: readonly PoleDef[];
-        neighbourhoods?: readonly NeighbourhoodPattern<any>[];
+        neighbourhoods?: readonly NeighbourhoodPattern[];
         districtKinds?: readonly DistrictKindDef[];
         cityPlans?: readonly CityPlanInput[];
     };
     /** Numbers changed on shipped entries, by id (objects merge, arrays replace). */
     patch?: {
         poles?: Record<string, DeepPartial<PoleDef>>;
-        neighbourhoods?: Record<string, DeepPartial<NeighbourhoodPattern<any>>>;
+        neighbourhoods?: Record<string, DeepPartial<NeighbourhoodPattern>>;
         districtKinds?: Record<string, DeepPartial<DistrictKindDef>>;
         cityPlans?: Record<string, DeepPartial<CityPlanInput>>;
     };
@@ -1268,7 +1286,7 @@ declare function createUrban(options?: UrbanOptions): {
     neighbourhoods: {
         ids: () => string[];
         get(id: string): {
-            pattern: NeighbourhoodPattern<any>;
+            pattern: NeighbourhoodPattern;
             /** Draws the pattern at `origin` and gives back what it put there. */
             compose: (b: UrbanBuilder, origin: Origin, o?: ComposeOptions) => UrbanPlan;
             marker: (origin: Origin, locale?: Locale) => {
@@ -1721,10 +1739,13 @@ declare const SILHOUETTE_TYPOLOGIES: Readonly<Record<string, SilhouetteFactory>>
 /** The default provider: the silhouette of game-floorplan for the typology, added to the builder with its shared random. */
 declare function createSilhouetteHouses(typologies?: Readonly<Record<string, SilhouetteFactory>>): HouseProvider;
 
-/** The vehicles of the fleet that park on a street: cars, SUVs, pickups and vans. */
+/**
+ * The vehicles of the fleet that park on a street: cars, SUVs, pickups and vans.
+ * @deprecated the fleet is content: pass `ids` to `createVehicleProvider` (`PARKED_VEHICLE_IDS` of `@adatechnology/game-kit-defaults` is the same list). The default is removed in the next major.
+ */
 declare const PARKED_VEHICLE_IDS: readonly string[];
 type VehicleProviderOptions = {
-    /** Ids of the fleet to choose from. Default `PARKED_VEHICLE_IDS`. */
+    /** Ids of the fleet to choose from. Default `PARKED_VEHICLE_IDS`, which is deprecated: pass the ids (`game-kit-defaults` has the same list). */
     ids?: readonly string[];
     /** Replaces the choice: the id for a request. The default picks by the spot, so the same pattern parks the same cars every time. */
     pick?: (request: VehicleRequest, ids: readonly string[]) => string;
@@ -1737,7 +1758,12 @@ type VehicleProviderOptions = {
  */
 declare function createVehicleProvider(options?: VehicleProviderOptions): VehicleProvider;
 type PlantProviderOptions = {
-    /** Planting table of a region. Default Brazil's. */
+    /** Chooses the species id for a context of the planting table and a key (`defaultPlantPicker` of `game-kit-defaults`, or the game's own). Without it the species come from the `region` table (deprecated default). */
+    pickSpecies?: (context: string, key: string) => string;
+    /**
+     * Planting table of a region, used only when `pickSpecies` is absent. Default Brazil's.
+     * @deprecated pass `pickSpecies`; the default is removed in the next major.
+     */
     region?: Region;
     /** Context of the table for each kind the patterns plant. */
     contexts?: Partial<Record<PlantRequest['kind'], string>>;
@@ -1747,11 +1773,11 @@ type PlantProviderOptions = {
     pick?: (request: PlantRequest, context: string, seed: string) => string;
 };
 declare const DEFAULT_PLANT_CONTEXTS: Readonly<Record<PlantRequest['kind'], string>>;
-/** A plant provider that asks the drawer for a species of the pack, drawn from the region's table for the kind (a tree on the sidewalk, a pine in the square). */
+/** A plant provider that asks the drawer for a species chosen by `pickSpecies`, from the table of the context for the kind (a tree on the sidewalk, a pine in the square). */
 declare function createPlantProvider(options?: PlantProviderOptions): PlantProvider;
 
 /** The ten patterns of the Galeria's sample sheet, in the order the page builds them. */
-declare const DEFAULT_PATTERNS: readonly NeighbourhoodPattern<any>[];
+declare const DEFAULT_PATTERNS: readonly NeighbourhoodPattern[];
 /** Where the sample sheet puts each pattern: a 3 x 3 grid 80 by 56 m apart, and the military cell off to the east. */
 declare const SAMPLE_CELLS: Readonly<Record<string, {
     x: number;
@@ -1759,11 +1785,11 @@ declare const SAMPLE_CELLS: Readonly<Record<string, {
 }>>;
 
 /** The patterns of the tower pack. */
-declare const TOWER_PATTERNS: readonly NeighbourhoodPattern<any>[];
+declare const TOWER_PATTERNS: readonly NeighbourhoodPattern[];
 /** Where the sample sheet puts them (pass it as `cells`). */
 declare const TOWER_SAMPLE_CELLS: Readonly<Record<string, {
     x: number;
     z: number;
 }>>;
 
-export { type BarSpec, type Block, type BlockBuilding, type BlockUse, type BuilderOptions, type BuildingOptions, COMPOSERS, type Cities, type CitiesOptions, type CityLayout, type CityPlanDef, type CityPlanInput, type CityScale, type ColorRule, type ComposeContext, type ComposeOptions, type Composer, type ConePart, type CrossarmSpec, type CrownPart, DEFAULT_CITY_PLANS, DEFAULT_DISTRICT_KINDS, DEFAULT_FACADES, DEFAULT_LIGHT_BUDGET, DEFAULT_MAX_FLOORS, DEFAULT_PATTERNS, DEFAULT_PLANT_CONTEXTS, DEFAULT_POLES, DEFAULT_PROP_COLORS, DEFAULT_ROAD_STYLE, DEFAULT_STOREY_PRESETS, DEFAULT_STREET, DEFAULT_TOWER_PRESETS, DEFAULT_URBAN_SEED, DEFAULT_WALK_STYLE, type DistrictKindDef, type DistrictKindText, type DoubleArmSpec, type DowntownParams, type FillBlockCityOptions, type FillBlockOptions, type Flatten, type FloodTowerSpec, type ForestOptions, type HistoricParams, type HouseProvider, type HouseRequest, type IndustrialParams, type ItemBox, type KindStats, type LabelPart, type Lake, type LampLightSpec, type LampSpec, type LanternSpec, type LayoutOptions, type LensSpec, type LightBudget, type LightPart, type Locale, type MastSpec, type MilitaryParams, type MountainParams, type NeighbourhoodPattern, type Origin, PARKED_VEHICLE_IDS, POLE_SHAPES, type PartStyle, type PatternText, type PlacementPart, type PlanDistrict, type PlanLandmark, type PlanLine, type PlanPoint, type PlanRect, type PlanePart, type PlantProvider, type PlantProviderOptions, type PlantRequest, type Point, type Pole, type PoleDef, type PoleOptions, type PoleShapeBuilder, type PropColors, type Providers, type RailwayParams, type Ramp, type Rect, type ResolvedDistrict, type River, type RiverBed, type RoadStyle, type RuralParams, SAMPLE_CELLS, SILHOUETTE_TYPOLOGIES, type SampleSheetOptions, type SilhouetteFactory, type SingleArmSpec, type StiltParams, type StreetOptions, type SuburbParams, TOWER_DEFAULTS, TOWER_PATTERNS, TOWER_SAMPLE_CELLS, type Terrain, type TerrainGrid, type TerrainLayer, type TerrainOptions, type TerrainPart, type TowerOptions, type TowerPreset, type TowerProvider, type TowerRequest, type Trig, type UrbanBuilder, type UrbanBuilderOptions, type UrbanKit, type UrbanKitCore, type UrbanOptions, type UrbanPart, type UrbanPlan, type UrbanScene, type VaultPart, type VehicleProvider, type VehicleProviderOptions, type VehicleRequest, type WalkStyle, type Wave, type WorkingClassParams, type WorldFrame, clamp, composePattern, createCities, createLightBudget, createPlantProvider, createSilhouetteHouses, createTerrain, createTowerDrawer, createUrban, createUrbanBuilder, createVehicleProvider, distanceToPolyline, drawBuilding, drawContainer, drawFence, drawGround, drawPine, drawRoad, drawSandbags, drawStreetGrid, drawStripLabel, drawTent, drawTerrain, drawTower, drawTree, drawWalk, drawWatchtower, drawWires, fillBlock, hash2, insideEllipse, insideRect, lerp, patternMarker, pickTowerPreset, smoothstep, towerPresetOf, towerStoreys };
+export { type BarSpec, type Block, type BlockBuilding, type BlockUse, type BuilderOptions, type BuildingOptions, COMPOSERS, type Cities, type CitiesOptions, type CityLayout, type CityPlanDef, type CityPlanInput, type CityScale, type ColorRule, type ComposeContext, type ComposeOptions, type Composer, type ConePart, type CrossarmSpec, type CrownPart, DEFAULT_CITY_PLANS, DEFAULT_DISTRICT_KINDS, DEFAULT_FACADES, DEFAULT_LIGHT_ALLOWANCE, DEFAULT_LIGHT_BUDGET, DEFAULT_MAX_FLOORS, DEFAULT_PATTERNS, DEFAULT_PLANT_CONTEXTS, DEFAULT_POLES, DEFAULT_PROP_COLORS, DEFAULT_ROAD_STYLE, DEFAULT_STOREY_PRESETS, DEFAULT_STREET, DEFAULT_TOWER_PRESETS, DEFAULT_URBAN_SEED, DEFAULT_WALK_STYLE, type DistrictKindDef, type DistrictKindText, type DoubleArmSpec, type DowntownParams, type FillBlockCityOptions, type FillBlockOptions, type Flatten, type FloodTowerSpec, type ForestOptions, type HistoricParams, type HouseProvider, type HouseRequest, type IndustrialParams, type ItemBox, type KindStats, type LabelPart, type Lake, type LampLightSpec, type LampSpec, type LanternSpec, type LayoutOptions, type LensSpec, type LightAllowance, type LightBudget, type LightPart, type Locale, type MastSpec, type MilitaryParams, type MountainParams, type NeighbourhoodPattern, type Origin, PARKED_VEHICLE_IDS, POLE_SHAPES, type PartStyle, type PatternText, type PlacementPart, type PlanDistrict, type PlanLandmark, type PlanLine, type PlanPoint, type PlanRect, type PlanePart, type PlantProvider, type PlantProviderOptions, type PlantRequest, type Point, type Pole, type PoleDef, type PoleOptions, type PoleShapeBuilder, type PropColors, type Providers, type RailwayParams, type Ramp, type Rect, type ResolvedDistrict, type River, type RiverBed, type RoadStyle, type RuralParams, SAMPLE_CELLS, SILHOUETTE_TYPOLOGIES, type SampleSheetOptions, type SilhouetteFactory, type SingleArmSpec, type StiltParams, type StreetOptions, type SuburbParams, TOWER_DEFAULTS, TOWER_PATTERNS, TOWER_SAMPLE_CELLS, type Terrain, type TerrainGrid, type TerrainLayer, type TerrainOptions, type TerrainPart, type TowerOptions, type TowerPreset, type TowerProvider, type TowerRequest, type Trig, type UrbanBuilder, type UrbanBuilderOptions, type UrbanKit, type UrbanKitCore, type UrbanOptions, type UrbanPart, type UrbanPlan, type UrbanScene, type VaultPart, type VehicleProvider, type VehicleProviderOptions, type VehicleRequest, type WalkStyle, type Wave, type WorkingClassParams, type WorldFrame, clamp, composePattern, createCities, createLightAllowance, createLightBudget, createPlantProvider, createSilhouetteHouses, createTerrain, createTowerDrawer, createUrban, createUrbanBuilder, createVehicleProvider, distanceToPolyline, drawBuilding, drawContainer, drawFence, drawGround, drawPine, drawRoad, drawSandbags, drawStreetGrid, drawStripLabel, drawTent, drawTerrain, drawTower, drawTree, drawWalk, drawWatchtower, drawWires, fillBlock, hash2, insideEllipse, insideRect, lerp, patternMarker, pickTowerPreset, smoothstep, towerPresetOf, towerStoreys };