Developer Diaries

In short: MKA Engine lets mods run recurring system work only on records selected by game day. The mod defines the date and processing rule; the engine supplies matching rows but does not choose the game's rule.

Developer Diary #32 explained when population-movement requests become visible. This diary asks how a system can find only records whose work is due.

Which records are due on a game day?

In a strategy game, not every village, group, or country needs work at the same time. Each group might have a next event day. When that day arrives, the group grows or another mod action runs. A record table holds groups in rows and their values and next dates in fields. A system is the recurring game rule that performs work on those records.

A system can visit every row and check its date. But when only a few groups are due, it still checks the others. “The day has arrived” can also mean two things: run only today's work, or include work due today and earlier. A notice that loses meaning after its date may need the first rule; maintenance that must be completed even when late may need the second. Whether an overdue event should run is a game-design choice; the engine should not guess.

Selecting matching records with two day rules

A mod creates a value index for a numeric day field in its own table. The index helps find rows by that field; it is not the game rule itself. A system uses an indexed field from that same table as its selection rule. It cannot select a field from another mod's table, and the selection is declared during setup.

The mod can choose one of two simple day rules. An exact match selects only rows for today. “Today or earlier” also includes records whose date has passed but whose work remains due. The selection uses the game day on which the system runs. An announcement meant for one date may use exact matching; maintenance that must catch up may include earlier dates. Each system has one day comparison; the mod evaluates more complex conditions in its own work.

The engine makes the selected row list available to the system. The mod must work from that list; it should not assume that every row between the list's bounds was selected. Selection does not expand the system's read or write permissions. If no rows are selected, there is no selected-row work to do.

Selection uses the record state from before the system runs. Writes, new records, and removals from earlier steps affect a later selection. If the system moves a record's date forward while working, that record is not selected again during the same work. The index is not stored as extra save data: it is derived from the record values and rebuilt when the game loads.

The day here is a value in the game's simulation calendar, not a text comparison of year, month, and day. If content describes an event as “this year, this month, this day,” the mod must convert that date to the game's day value. That lets it compare the row's date with the day of the current simulation step on the same scale. The game chooses its calendar, and the mod uses that calendar's date conversion to decide which value to write into the field. A numeric field alone does not guarantee that the intended date meaning is correct: if content counts from a different starting day, selection will still compare the numbers, but they may not match the calendar event the mod intended.

How does the guide example use selection?

The guide example keeps a next processing day for each group. The system increases the value of groups due today or earlier and moves their next day forward. The 30-day interval in the example belongs to that sample mod; it is not MKA Engine's default population rule. Another game might use the same mechanism for a dated notice, overdue work, or a calculation on a different schedule. The engine does not set the day or the work; it provides the selection mechanism.

Notices, overdue work, and reloaded records

Start with a dated announcement. The content author gives each notice the game day on which it should appear. If the system asks for an exact match, only records for that day are selected. A notice whose date has passed is not automatically treated as current when a later step runs. If the design calls for a late notice to remain eligible, the choice changes: the author can choose “today or earlier.” That choice does not create or display the announcement text. It only determines which records the system processes. Visibility, wording, and the game's response remain the mod's responsibility.

Now consider the game advancing several calendar days at once. Suppose a record's due day is earlier than the current day when the system next runs. Exact-day selection looks for equality, so it leaves that row out. “Today or earlier” can select it because the old date represents work that may still need attention. This is not a general guarantee that every missed event will run. The rule is a way to find overdue work; when the mod examines the row, its own fields and game logic must decide whether the work still makes sense. That is the key difference between a notice that loses meaning after its date and maintenance that should still be completed when late.

A third situation is loading a saved game again. The index is not separate saved-game data. When the game loads, the engine rebuilds it from the day values in the record table. The mod author therefore needs to maintain the actual date field that selection relies on. If a saved record still carries an earlier date as its “next work day,” the rebuilt index uses that value, and “today or earlier” can find it again. If the mod moves the date forward after completing the work, a later selection sees the updated value. The index does not mark the task complete or write a new date on the mod's behalf.

Together, these examples expose three different design choices in the same mechanism: exact-day matching, allowing overdue work, and continuing from record values after a reload. They are not ready-made announcement, maintenance, or persistence systems for a particular game. They illustrate the date meaning a mod author must choose. The right option depends on what the content's day field means.

Matching rows are separate records, not a range

A system's list does not have to be a continuous slice of the calendar's records. Imagine a table with two early-dated groups, another group due much later, and one matching row between them. The system processes only rows that match its rule; it must not assume every row between the first and last selected row also matched. The engine returns selected rows in ascending row order. With parallel work, each work partition preserves that order in its own list; a partition with no selected rows is not called.

A “work partition” is the slice of rows the engine handles in one system call. The mod asks for the selected-row list and limits its work to those rows. The first and last positions do not mean every position in between was selected; the selected-row list itself is decisive. This matters when thinking about ordered data: ascending order is a consistent presentation of the selected records, not a geographical, historical, or importance ranking in the game world.

That ordered view does not sort results by their meaning in the game. Selected records arrive in ascending row order; this does not mean oldest date to newest, largest population to smallest, or north to south on a map. If content needs one of those priorities, the mod must read the relevant field and make that decision itself. Day selection only finds rows that satisfy the date rule.

The moment of selection is part of this view too. The system starts from the set of eligible records that exists before it runs. If an earlier step changed a group's day, added a group, or removed a record, the later selection uses the changed table. By contrast, when the selected-row system moves a row's date forward during its own call, that record is not selected again from a newly rebuilt list in the middle of that call. Authors should not assume that a date change inside a loop recreates the loop's starting set.

For example, an earlier phase of a calendar step might update a group's planned maintenance day to today. If selection runs after that phase, the group can enter today's work set. The system handles it and advances its next maintenance day; it does not then walk the same selection again using the new date. A later selection sees the system's earlier writes. This distinction keeps “records ready at the start of this work” separate from “records moved to a later date after processing.”

This also gives mod authors a practical check: for each selected row, which fields will the system read and which will it change? The read and write fields declared when the system is registered remain the fields available for that work; row selection does not grant access to additional fields. For example, configuring a system to update only the next due day does not turn its row-selection ability into permission to change population, treasury, or another field. The fields needed by the work must be declared in the system itself.

This mechanism does not keep a task-completed flag like an event queue. With “today or earlier,” a record may remain eligible on the next step if the mod leaves its date unchanged. For one-time work, the mod must update its own state or move the next day forward. Likewise, an exact-day rule does not automatically catch overdue work.

The game and mod define what a day means

Declaring the index and day rule explicitly prevents the engine from treating every numeric field as a date. Game content gives the day its meaning, and the mod defines what happens when the day arrives. The engine only finds matching records. This leaves exact-day and overdue behavior in the game's design while making the system's input clear.

For a mod author, selection is a relationship declared during setup: the field must be numeric, belong to the same mod-owned table, have an index, and be used by the system as its selection rule. The rule does not reinterpret another field as a date after the system starts. Each system has one comparison, such as “today or earlier.” If a mod needs both a date range and another condition, it should not assume that this extra logic is hidden inside the selection. It can evaluate its own game condition on the rows that were selected.

Keeping setup separate from runtime also helps avoid mistakes. The table and field relationship is checked when the index and selection are registered. During execution, the system receives its own selected rows. That is different from carrying the list into another mod's table or requesting it from a call that did not define the selection. Content authors should also explain what the date means: is it the next maintenance day, or the date of a one-time event? Once that meaning is clear, it is easier to follow why overdue records are included or left out.

When reviewing that choice, an author can compare several date situations with the game's own rule: a record due today, one due earlier, one due later, and a step that advances past a record's date. These examples do not ask the engine to make the same choice for every design. They are prompts for making the intended overdue policy explicit. Should a late announcement still appear, or is it valid only on its date? Should maintenance remain pending into a later step? Content design needs to answer those questions.

What work does selection leave to the mod?

The index is an additional lookup structure rebuilt when the game loads. No timing or memory measurement was published for this change, so we do not claim a speed gain. Selection can limit the rows a system processes when only some are due. If every row is ready, the system still receives many rows; we cannot conclude that the index lowers total time for every game or table size.

The selection field must be indexed in the mod's own table, and the system must use a field from that same table; invalid field selections are rejected. The selected-row list is available only while the selecting system runs; requesting it in another context stops the mod. The engine does not correct a wrong day rule or the mod's game logic.

Questions for a real game calendar

The next step is to connect this selection to a real game's calendar: show which work is due on which day, how overdue work is handled, and what changes on each selected record.

Frequently asked questions

Links

• MKA Engine
• Contact
• Developer diaries
• Previous diary: population moves in systems