Source code

An NPCFlag<T> represents a typed key-value pair attached to an NPC, used to configure or store extra data about that NPC. Flags allow flexible, extendable customization without changing the NPC's core logic.

Each flag has:

• A unique key (string identifier)
• A defaultValue
• A predicate accepts(value: T?) to validate if a given value is valid for this flag

Custom flags are especially useful to keep track of additional NPC data, for example configuration entries or metadata that you want to persist on the NPC instance.

If you spawn an NPC based on some config entry, you can create a custom flag to keep a reference to that config:

When creating a flag, you can specify an optional predicate (called valueTester) that validates if a value is acceptable for the flag. For example, to allow only non-null values greater than zero:

val POSITIVE_DISTANCE_FLAG = NPCFlag.flag("positive_distance", 10) { it != null && it > 0 }

If no predicate is needed, it defaults to accept all values:

val CUSTOM_FLAG: NPCFlag<String> = NPCFlag.flag("npc_custom_flag", "Hello, world!")

Then assign it when building or modifying the NPC:

.flag(CUSTOM_FLAG, "Custom flag set!")

This allows you to later retrieve or modify the NPC based on its original config, or resolve further settings dynamically on NPC interaction.

All flagged builders provide two methods to set flags:

• Use NPCFlag.flag(key, defaultValue) { ... } to create new custom flags.
• The valueTester predicate should return true if the value is valid for the flag.
• Assign flags with .flag() or .flags() on any flagged builder.
• Custom flags help keep additional NPC-related data accessible and modifiable during runtime.