body_marking_collection 
Vars | |
| entries | Every worn entry in the order it was added. A zone's markings are this list filtered by zone. |
|---|---|
| key_cache | zone -> cache key fragment. Dropped on a version bump or a new entry revision. |
| key_cache_revision | The entry revision key_cache was built at. |
| key_cache_version | The version key_cache was built at. |
| version | Bumped by every structural change: a zone or an entry added, an entry removed or replaced. Read-only outside this type, where only BODY_MARKING_ZONE_VIEWS() reads it. |
| zone_cache | zone -> that zone's entries in order, for every zone wearing any, in zone order. Built on first use after a version bump and always replaced rather than edited, so a list handed out earlier stays a stable snapshot. Read-only outside this type, where only BODY_MARKING_ZONE_VIEWS() reads it. |
| zone_cache_version | The version zone_cache was built at. Read-only outside this type, where only BODY_MARKING_ZONE_VIEWS() reads it. |
| zones | Zones in the order they first appeared. An emptied zone keeps its place, as the nested map kept its key. |
Procs | |
| add_entry | Adds an entry after every entry already on its zone, adding the zone first when it is absent. |
| add_zone | Adds a zone with no markings yet, where a new key of the nested map would have gone: at the end. |
| blocking_entry | Returns the entry that keeps a marking off a zone: one wearing the same marking or, unless told not to look, one wearing another marking of its exclusion group. add_entry(), replace_entry() and set_zone_entries() refuse through here, and character setup asks it which markings a zone can still take. |
| cache_key_for_zone | Returns a string standing for one zone's markings, in order, with their colours and glow. |
| copy | Returns a new collection with new entries in the same zones and order, colours and glow. Nothing is shared. |
| enforce_zone_limits | Drops what editing could never have put on a zone, keeping the order of the rest: a second marking of an exclusion group, then every entry past MAXIMUM_MARKINGS_PER_LIMB. A save from before version 21 gets this once as it loads; nothing else calls it, so a save written since keeps what it holds. |
| entries_for_zone | Returns one zone's entries in order. |
| entry_count | Returns how many entries there are across every zone. |
| find_entry | Returns the entry wearing a marking on a zone. |
| has_zone | Returns whether a zone is present, with markings or emptied. |
| marking_names | Returns the names one zone wears, in order. |
| overwrite_zones_from | Gives every zone another collection holds that collection's entries, as assigning its zone maps did. |
| remove_entry | Removes an entry. Its zone stays present, emptied or not. |
| replace_entry | Puts a replacement in an entry's place, so it keeps its position on the zone. |
| reseed_colors | Gives every marking its starting colour again, as a colour reset does, except locked ones: a locked marking keeps its colour, a custom one a save holds included. Glow is left alone. |
| serialize | Rebuilds the nested shape preferences.json stores: zone -> (marking name -> list(color, emissive)). |
| set_zone_entries | Replaces everything on one zone. An absent zone is added at the end, a present one keeps its place. |
| set_zone_from_list | Replaces everything on one zone from the nested shape a savefile holds, with new entries. |
| shallow_copy | Returns a new collection holding these same entries. |
| validate_for_species | Returns the entries a species may not wear without mismatched parts, each asked of its marking's allows_species(): the one check of a whole character's markings against a species. This only reports mismatches: saved markings must never be removed because a character changes species. |
| zone_count | Returns how many zones are present, emptied ones included. |
| zone_length | Returns how many entries one zone wears. |
| zone_views | Returns the entries of every zone that wears any, in zone order. |
Var Details
entries
Every worn entry in the order it was added. A zone's markings are this list filtered by zone.
key_cache
zone -> cache key fragment. Dropped on a version bump or a new entry revision.
key_cache_revision
The entry revision key_cache was built at.
key_cache_version
The version key_cache was built at.
version
Bumped by every structural change: a zone or an entry added, an entry removed or replaced. Read-only outside this type, where only BODY_MARKING_ZONE_VIEWS() reads it.
zone_cache
zone -> that zone's entries in order, for every zone wearing any, in zone order. Built on first use after a version bump and always replaced rather than edited, so a list handed out earlier stays a stable snapshot. Read-only outside this type, where only BODY_MARKING_ZONE_VIEWS() reads it.
zone_cache_version
The version zone_cache was built at. Read-only outside this type, where only BODY_MARKING_ZONE_VIEWS() reads it.
zones
Zones in the order they first appeared. An emptied zone keeps its place, as the nested map kept its key.
Proc Details
add_entry
Adds an entry after every entry already on its zone, adding the zone first when it is absent.
A zone wears each marking at most once, which the name-keyed nested map used to guarantee, and at most one marking of an exclusion group.
Arguments:
- entry: the entry to add. It is held by reference, not copied.
Returns:
- TRUE if added. FALSE for an entry without a marking or off the marking zones, or one its zone already wears the marking of, or a marking of its exclusion group.
add_zone
Adds a zone with no markings yet, where a new key of the nested map would have gone: at the end.
Arguments:
- zone: one of GLOB.marking_zones. Anything else is ignored.
Returns:
- TRUE if the zone was added, FALSE if it was already present or is not a marking zone.
blocking_entry
Returns the entry that keeps a marking off a zone: one wearing the same marking or, unless told not to look, one wearing another marking of its exclusion group. add_entry(), replace_entry() and set_zone_entries() refuse through here, and character setup asks it which markings a zone can still take.
Arguments:
- zone: the zone the marking would go on.
- marking: the marking that would go on.
- ignored: an entry to leave out, as the one a replacement takes the place of.
- check_group: FALSE to look for the same marking only.
Returns:
- /datum/body_marking_entry, or null when nothing on the zone stands in the way.
cache_key_for_zone
Returns a string standing for one zone's markings, in order, with their colours and glow.
Arguments:
- zone: the zone to describe.
Returns:
- string: each entry's cache_key() joined by "-", or "" for none. Cached until the zone or an entry changes.
copy
Returns a new collection with new entries in the same zones and order, colours and glow. Nothing is shared.
Arguments:
- allow_emissives: FALSE to copy every entry without its glow, as a body is dressed while its character's allow_emissives preference is off. The glow this collection holds is kept either way.
Returns:
- /datum/body_marking_collection: the copy.
enforce_zone_limits
Drops what editing could never have put on a zone, keeping the order of the rest: a second marking of an exclusion group, then every entry past MAXIMUM_MARKINGS_PER_LIMB. A save from before version 21 gets this once as it loads; nothing else calls it, so a save written since keeps what it holds.
Returns:
- number: how many entries were dropped.
entries_for_zone
Returns one zone's entries in order.
Arguments:
- zone: the zone to read.
Returns:
- list: a shared, read-only list of entries, or null when the zone wears nothing, emptied or absent.
entry_count
Returns how many entries there are across every zone.
find_entry
Returns the entry wearing a marking on a zone.
Arguments:
- zone: the zone to look on.
- name: the marking's name.
Returns:
- /datum/body_marking_entry, or null when the zone doesn't wear that marking.
has_zone
Returns whether a zone is present, with markings or emptied.
Arguments:
- zone: the zone to look for.
marking_names
Returns the names one zone wears, in order.
Arguments:
- zone: the zone to read.
Returns:
- list: a new list of marking names, or null when the zone wears nothing.
overwrite_zones_from
Gives every zone another collection holds that collection's entries, as assigning its zone maps did.
A zone present here keeps its place and a new one goes at the end. A zone the other holds emptied is emptied here too. Each zone is taken whole, as the other holds it. The entries are shared, not copied.
Arguments:
- other: the collection whose zones win.
remove_entry
Removes an entry. Its zone stays present, emptied or not.
Arguments:
- entry: the entry to remove.
Returns:
- TRUE if the entry was held here and is now gone.
replace_entry
Puts a replacement in an entry's place, so it keeps its position on the zone.
Arguments:
- old_entry: the entry to replace.
- replacement: the entry taking its place. It must sit on the same zone and not wear a marking another entry on that zone already wears, or a marking of that entry's exclusion group.
Returns:
- TRUE if replaced.
reseed_colors
Gives every marking its starting colour again, as a colour reset does, except locked ones: a locked marking keeps its colour, a custom one a save holds included. Glow is left alone.
Arguments:
- features: the character's features, where a following mode reads its mutant colour.
- species: the character's species.
serialize
Rebuilds the nested shape preferences.json stores: zone -> (marking name -> list(color, emissive)).
Zones and entries keep their order, an emptied zone writes as [], colours are the stored lowercase #rrggbb and emissive is the integer 0 or 1, so a loaded save writes back byte for byte. With no zones this is an empty list, which json_encode() writes as [].
Returns:
- list: a new nested list the caller owns.
set_zone_entries
Replaces everything on one zone. An absent zone is added at the end, a present one keeps its place.
Arguments:
- zone: one of GLOB.marking_zones.
- zone_entries: the zone's new entries, in order. They are held by reference. Entries for another zone, repeats of a marking and a second marking of an exclusion group are skipped. Null or an empty list empties the zone, which stays present.
- keep_group_conflicts: TRUE to keep markings of one exclusion group side by side, as a save or another collection holds them. Only the savefile loader and whole-zone transfers pass it; the version 21 savefile pass resolves what a save held.
Returns:
- TRUE if the zone was set.
set_zone_from_list
Replaces everything on one zone from the nested shape a savefile holds, with new entries.
Arguments:
- zone: one of GLOB.marking_zones.
- raw_zone: marking name -> list(color, emissive), read as body_marking_entries_from_list() reads it.
Returns:
- TRUE if the zone was set.
shallow_copy
Returns a new collection holding these same entries.
Adding, removing or replacing entries on one leaves the other alone, but a recoloured entry changes in both: the sharing the nested lists' shallow Copy() gave, kept until each copy site is decided on.
Returns:
- /datum/body_marking_collection: the copy.
validate_for_species
Returns the entries a species may not wear without mismatched parts, each asked of its marking's allows_species(): the one check of a whole character's markings against a species. This only reports mismatches: saved markings must never be removed because a character changes species.
Arguments:
- species_id: the species' id.
- allow_mismatched: TRUE when mismatched parts are allowed, which allows every marking.
Returns:
- list: a new list of the entries not allowed, in order, or null when every entry is.
zone_count
Returns how many zones are present, emptied ones included.
zone_length
Returns how many entries one zone wears.
Arguments:
- zone: the zone to count.
zone_views
Returns the entries of every zone that wears any, in zone order.
The returned list and the lists inside it are shared and must not be edited: limbs hold these zone lists as their markings. A structural change builds new ones, so a list already handed out keeps what it held. A zone that wears nothing, emptied or absent, has no list here; has_zone() tells the two apart. Hot callers read the same views through BODY_MARKING_ZONE_VIEWS(), which calls this only when they are out of date.
Returns:
- list: zone -> list of entries, or null when no zone wears any.