BlueGit

timfa questward

Files

questward / shared / world / season.js

season.js

season.js 7.4 KiB Download Raw
1import { resolveState, statesForType } from "../definitions/tileSprites.js";
2
3/** Calendar seasons for outdoor ground/block visuals (server local clock). */
4export const SeasonId = Object.freeze({
5 spring: "spring",
6 summer: "summer",
7 fall: "fall",
8 winter: "winter"
9});
10
11/** @deprecated Prefer {@link SeasonId}; same four-way calendar for regrow rates. */
12export const GrowthSeasonId = SeasonId;
13
14export const SEASON_STATE_ORDER = Object.freeze([
15 SeasonId.spring,
16 SeasonId.summer,
17 SeasonId.fall,
18 SeasonId.winter
19]);
20
21/**
22 * Season from a local Date / unix ms.
23 * Spring Mar–May; summer Jun–Aug; fall Sep–Nov; winter Dec–Feb.
24 */
25export function seasonIdAt (now = Date.now())
26{
27 const month = new Date(now).getMonth();
28 if (month >= 2 && month <= 4)
29 { return SeasonId.spring; }
30 if (month >= 5 && month <= 7)
31 { return SeasonId.summer; }
32 if (month >= 8 && month <= 10)
33 { return SeasonId.fall; }
34 return SeasonId.winter;
35}
36
37/** Alias of {@link seasonIdAt} (regrow rates use the same four seasons). */
38export const growthSeasonIdAt = seasonIdAt;
39
40/**
41 * Tree / flower / herb exhaust→respawn duration multiplier by growth season.
42 * Summer & fall: 1×; winter: 2×; spring: 0.75× (25% faster).
43 */
44export function regrowDurationMultiplier (growthSeasonId)
45{
46 if (growthSeasonId === SeasonId.winter)
47 { return 2; }
48 if (growthSeasonId === SeasonId.spring)
49 { return 0.75; }
50 return 1;
51}
52
53/** Scale a base exhaust duration (ms) for the current growth season. */
54export function scaleRegrowDurationMs (baseMs, nowOrGrowthSeason = Date.now())
55{
56 const growth = typeof nowOrGrowthSeason === "string"
57 ? nowOrGrowthSeason
58 : growthSeasonIdAt(nowOrGrowthSeason);
59 return Math.max(1, Math.round((baseMs | 0 || 0) * regrowDurationMultiplier(growth)));
60}
61
62/**
63 * True when this type has full summer/fall/winter visual states.
64 * Optional `spring` is allowed; types without it fall back to summer in spring.
65 * Only outdoor types should ship these; indoor types never need them.
66 */
67export function typeHasSeasonalStates (states)
68{
69 const set = new Set(states ?? []);
70 const hasSummer = set.has(SeasonId.summer) || set.has("grass");
71 return hasSummer && set.has(SeasonId.fall) && set.has(SeasonId.winter);
72}
73
74/**
75 * Optional per-state seasonal overlay (`boulder-winter`, `copper-ore-winter`).
76 * Used when a type only overrides some seasons and otherwise keeps the base sprite.
77 */
78export function isSeasonalOverlayVariant (state)
79{
80 if (typeof state !== "string" || isSeasonalStumpState(state))
81 { return false; }
82 for (const season of SEASON_STATE_ORDER)
83 {
84 const suffix = `-${season}`;
85 if (state.endsWith(suffix) && state.length > suffix.length)
86 { return true; }
87 }
88 return false;
89}
90
91export function seasonalOverlayBaseState (state)
92{
93 if (!isSeasonalOverlayVariant(state))
94 { return state; }
95 for (const season of SEASON_STATE_ORDER)
96 {
97 const suffix = `-${season}`;
98 if (state.endsWith(suffix))
99 { return state.slice(0, -suffix.length); }
100 }
101 return state;
102}
103
104export function seasonalOverlayState (baseState, seasonId)
105{
106 if (!baseState || isSeasonalOverlayVariant(baseState) || isSeasonalStumpState(baseState))
107 { return null; }
108 const season = seasonId ?? SeasonId.summer;
109 if (
110 season === SeasonId.spring
111 || season === SeasonId.summer
112 || season === SeasonId.fall
113 || season === SeasonId.winter
114 )
115 { return `${baseState}-${season}`; }
116 return null;
117}
118
119/** Summer (or legacy grass) look when spring art is absent. */
120function resolveSummerVisualState (states)
121{
122 if (states.includes(SeasonId.summer))
123 { return SeasonId.summer; }
124 if (states.includes("grass"))
125 { return "grass"; }
126 return null;
127}
128
129/**
130 * Pick the visual state for the current season when the type supports seasons.
131 * Authored stump states stay exhausted visuals (seasonal stump sprite).
132 * Full seasonal outdoor types ignore authored live state (calendar drives the look).
133 * Spring uses `spring` when present, otherwise the summer look.
134 * Types with only some overlays (e.g. `*-winter`) use the overlay when present, else the base.
135 */
136export function resolveSeasonalVisualState (states, authoredState, seasonId)
137{
138 const season = seasonId ?? SeasonId.summer;
139 if (isSeasonalStumpState(authoredState) && typeHasSeasonalStates(states))
140 {
141 const stump = treeStumpStateForSeason(season);
142 if (states.includes(stump))
143 { return stump; }
144 if (states.includes(authoredState))
145 { return authoredState; }
146 return resolveState(states, authoredState);
147 }
148 if (typeHasSeasonalStates(states))
149 {
150 if (season === SeasonId.spring)
151 {
152 if (states.includes(SeasonId.spring))
153 { return SeasonId.spring; }
154 const summer = resolveSummerVisualState(states);
155 if (summer)
156 { return summer; }
157 }
158 if (season === SeasonId.summer)
159 {
160 const summer = resolveSummerVisualState(states);
161 if (summer)
162 { return summer; }
163 }
164 if (states.includes(season))
165 { return season; }
166 return resolveState(states, authoredState);
167 }
168 const resolved = resolveState(states, authoredState);
169 const base = seasonalOverlayBaseState(resolved);
170 const overlay = seasonalOverlayState(base, season);
171 if (overlay && states.includes(overlay))
172 { return overlay; }
173 // Spring overlays are optional; fall back to the unseasoned base.
174 if (season === SeasonId.spring && base && states.includes(base))
175 { return base; }
176 if (base && states.includes(base))
177 { return base; }
178 return resolved;
179}
180
181/** True when authored state is a tree stump (`summer-stump`, …). */
182export function isSeasonalStumpState (state)
183{
184 return typeof state === "string" && (state === "stump" || state.endsWith("-stump"));
185}
186
187/** Exhausted tree visual for a calendar season (spring shares summer stump art). */
188export function treeStumpStateForSeason (seasonId)
189{
190 const season = seasonId === SeasonId.fall || seasonId === SeasonId.winter
191 ? seasonId
192 : SeasonId.summer;
193 return `${season}-stump`;
194}
195
196/** Preferred catalog default among seasonal states. */
197export function preferredSeasonalDefaultState (states)
198{
199 if (!states?.length)
200 { return null; }
201 if (states.includes(SeasonId.summer))
202 { return SeasonId.summer; }
203 if (states.includes("grass") && states.includes(SeasonId.fall))
204 { return "grass"; }
205 return states[0];
206}
207
208/**
209 * Ordered seasonal visual states to cycle in the editor (spring/summer/fall/winter).
210 * Legacy `grass` stands in for summer when `summer` is absent.
211 * Returns null when the type is not fully seasonal.
212 */
213export function seasonalCycleStates (states)
214{
215 if (!typeHasSeasonalStates(states))
216 { return null; }
217 const out = [];
218 if (states.includes(SeasonId.spring))
219 { out.push(SeasonId.spring); }
220 if (states.includes(SeasonId.summer))
221 { out.push(SeasonId.summer); }
222 else if (states.includes("grass"))
223 { out.push("grass"); }
224 if (states.includes(SeasonId.fall))
225 { out.push(SeasonId.fall); }
226 if (states.includes(SeasonId.winter))
227 { out.push(SeasonId.winter); }
228 return out.length >= 2 ? out : null;
229}
230
231/** Map a seasonal visual state name to a SeasonId (legacy `grass` → summer). */
232export function seasonIdFromVisualState (state)
233{
234 if (
235 state === SeasonId.spring
236 || state === SeasonId.fall
237 || state === SeasonId.winter
238 || state === SeasonId.summer
239 )
240 { return state; }
241 if (state === "grass")
242 { return SeasonId.summer; }
243 return null;
244}
245
246/** States the editor may cycle/paint (excludes seasonal overlays, tree stumps, and autotile masks). */
247export function placeableStatesForType (catalog, layer, key)
248{
249 return statesForType(catalog, layer, key)
250 .filter((state) =>
251 !isSeasonalOverlayVariant(state)
252 && !isSeasonalStumpState(state)
253 && !/^\d+$/.test(String(state))
254 );
255}