Developer Diary #32: Population Moves in Systems

In short: MKA Engine now lets mods queue population-movement requests from system work. The engine does not apply those requests immediately while a system is running; it handles them after the systems finish, at the boundary of the game step. A mod author can therefore calculate a rule for a group inside a system, while the game—not the engine—still decides the conditions for migration and the number of people involved.

What was the problem?#

A strategy game often tracks its population not person by person, but as groups of people who live in one place or share relevant traits. A group’s size, location and other game-specific properties work together. A game might calculate, under its own rules, that people should move from a rural group into a group in a city. The engine’s job is not to decide whether that game rule is right; it is to apply a change consistently using the information supplied by the game and its mods.

A mod is an extension that adds rules or content to a game. In Developer Diary #26, we described mod access to population and market calculations and the limits of an initial large-scale measurement. This diary focuses on a narrower question: when system work makes a movement request, where and when does the engine apply it?

MKA Engine runs different kinds of work at different times. A system usually performs a separate calculation for each record or group; for example, it can evaluate the game’s conditions for each population group. A hook runs at a step boundary and can bring together results from several groups. A command entered by a player or a timer also uses that second, boundary-based path. This distinction describes how the engine schedules work. It does not choose which game rule should run.

Before this change, population-movement requests could be made from a hook, command or timer. If a system produced a separate decision for each group, it had to pass those decisions to a hook to request the moves. That was not the wrong design for every game: a content author who wants to calculate a combined result and then apply it may prefer a hook. But when a move request already comes from the calculation for one group, an additional handoff becomes a required architectural choice.

It helps to separate selecting groups from applying their moves. The engine also offers a separate way to list live records with a marker, in order; system movement requests do not require it. A mod can use that list instead of writing its own search loop, but the engine still scans the marker field.

How did we solve it?#

A mod author can now make a population-movement request while a system is running. The system can evaluate the game’s rule using the groups it is processing and the information it is allowed to read. If, for example, the game decides that a group should move to a different place, the mod can queue that request from the system itself. The engine checks the source and form of the request, but the mod decides which group moves, where it goes and which game conditions trigger the move.

A queued request does not change the population table while the system call is running. Once the systems have finished, the engine reaches the step boundary. It gathers the movement requests left by successful system work and applies them before the mod’s later hooks. Think of a meeting where people submit changes to a shared list and the list is updated after the meeting ends. The limit of the analogy is that the actual game data changes according to the game’s rules and the requests the mod submitted.

This order also explains what data is visible during the same step. A read inside the system stage does not see movements queued during that stage; the engine handles them only after the stage finishes. So a system cannot queue a move, immediately read the changed population back and make a second decision from the new location in that same stage. This does not cancel the move in the game. It defines which phase of the work can see it. Mod authors need to design chained decisions around that boundary.

The engine does not apply requests according to whichever parallel worker happens to finish first. It establishes a fixed order for systems and the portions of their work; each portion’s requests also remain in the order they were made. The result does not have to change just because workers complete at different speeds. Here, “same result” refers only to the documented ordering of this population-movement path; it is not a guarantee about every other game rule or the entire simulation.

For each request, the engine checks that the source group is live, the destination is valid and the requested change is defined. This does not validate whether migration is the right game rule; it checks whether the engine can apply the request to the available data. An invalid request is rejected at the call level.

Consider a small example. In a strategy game, population groups looking for work in a certain market area might be eligible to move elsewhere. This is not a ready-made game rule added by this engine change; it is an illustrative rule a content author could choose. The mod’s system evaluates market access, or another condition defined by the game, for each group. It creates a movement request for a group that meets the condition. The engine applies the requests at the step boundary rather than during the system’s work. A game hook can then calculate totals using the new locations.

If another calculation needs the new location, schedule it after the boundary where the moves are applied; otherwise, the game rule can use the change on the next step.

A list requested inside a system covers only live groups in that work portion, and the marker field must be declared readable by the system. A hook at the barrier can see the wider table. But if that same call has a pending write to the marker field, the listing request is rejected; the engine does not silently return an old list. Keep the write and listing in separate calls, and request the list after the write is visible.

What did we see?#

The Turkish and English mod guides describe system movement, when requests become visible and the listing limits. The code applies requests in the order documented by the sources.

Tests were not run while preparing this draft, so we report no test result.

The reviewed sources contain no new timing comparison under the same world and workload. A count of moved groups alone does not show step duration, so we make no speed or memory-savings claim. The concrete change is that a mod author can issue a movement request directly from system work.

Why did we choose this approach?#

Parallel system work can finish in different orders as worker speeds vary. The engine applies requests in a defined order instead of using completion time, so the result does not depend on which worker finishes first.

A system suits a separate rule calculation for each group; a hook suits a total across groups or the result of a whole step. Player commands and timers run when their own trigger occurs. Mod authors should choose a call path by the scope and timing of the rule, not an assumed speed benefit; the mod still decides how conflicting moves should resolve. Hooks, commands and timers remain available.

What does it cost?#

Requests remain invisible during the system stage, so a mod cannot read a new location there. Each work portion has a request limit: exceeding it faults that portion and drops its queued moves. The limit counts requests, not people.

What comes next?#

The sources do not provide a ready-made game rule using this feature or a new measurement under the same conditions. A meaningful follow-up would need evidence from a real game rule or a comparable measurement.

Frequently asked questions#

For earlier context on population and market operations for mods, see Developer Diary #26. You can also visit MKA Engine, the developer diaries, and contact.