graffiti

Vars
admin_areas	Packed placement -> the area admin_rows() shows and sorts it under, until the placements change.
admin_orders	Sort -> every packed placement in that order, for admin_rows(), until the placements change.
anchor_resolvers	Anchor kind -> the /datum/callback a system registered to turn an anchor of that kind into a turf, or null.
art	Art hash -> the flat art, for every art a placement uses.
art_byte_budget	Most bytes of art the map keeps. Tests lower it.
art_bytes	The bytes of every art in `art`, as art_size() counts them.
art_icons	graffiti_art_hash() -> the icon graffiti_art_icon() drew of that art, up to GRAFFITI_ICON_CACHE of them.
art_refs	Art hash -> how many placements use it.
ckey_arts	Ckey -> art hash -> how many of its placements use it.
ckey_placements	Ckey -> its packed placements, in the order its own caps evict them: by "at", then as `placements` orders them.
composite_line	The editors and paint jobs waiting for composite_share, in the order they first asked, -> when each last asked.
composite_share	How many ms of composites may still run now, every painter's together. Below zero, they went over, and that is paid back first.
composite_share_at	When composite_share was last topped up.
decoded	Art hash -> graffiti_art_decode() of the arts and stack composites decoded while the map loads, for the load's merges and sheets, within GRAFFITI_DECODE_BUDGET. Null once build_sheets() has drawn them.
displayed_unique	Art hash -> how many shown placements use it, so its length counts the unique arts shown.
dormant	The packed placements not shown this round.
editors	Ckey -> that player's graffiti editor. A player has one at a time, opened through graffiti_editor_for().
frozen	Whether the round-end save has run, after which nothing is written.
glow_icons	graffiti_art_hash() -> the glow mask graffiti_glow_icon() drew of that art, up to GRAFFITI_ICON_CACHE of them.
libraries	Account ckey -> its loaded graffiti library.
library_revision	The last revision any graffiti library took. A library loaded again after a purge never repeats one an open window saw.
library_root	The directory library files go under. Tests point it at a scratch directory; admins can't edit it (vv_edit_var()).
load_resumed_at	TICK_USAGE when the background load last went on in a tick, which its share of the tick counts from.
load_share	Percent of each tick the load takes at most: GRAFFITI_LOAD_SHARE, or the whole tick in unit tests and benchmarks, which time the load's work rather than spread it.
loaded	Whether the map's graffiti has loaded, which it does in the background once the game reaches the lobby (load_in_background()): until then nothing is placed, saved or deleted by an admin.
loaded_templates	Map templates loaded this round on station levels, oldest first: list("id" = the template's map file, "x", "y", "z" = its low corner, "w", "h"). Recorded from SSmapping's init on, before this subsystem initializes.
map_path	Where the map's graffiti file is. Tests point it at a scratch file through load_file().
paint_jobs	Ckey -> that player's running paint job. A player runs one at a time.
placement_cap	Most placements the map keeps. Tests lower it.
placement_info	Packed placement -> list(ckey, art hash, "at", pid, "who", whether it lasts this round only), read through the GRAFFITI_INFO_* indices: what placement operations read of a placement without unpacking it.
placements	Every placement, packed, in the order they were placed, which each tile's stack follows.
save_failure_told	Whether the admins were told this round that the map file couldn't be written.
save_pending	The timer that will write the map file, while one is pending.
seen	Ckey -> when its owner last connected, as ten-digit unix seconds in text.
sheet_root	The directory every map's sheet files go under. Tests move it.
sheets	Stack key -> list(the sheet file's resource, whether it holds the stack's glow mask).
sheets_built	How many sheet files the last build_sheets() wrote rather than reused.
shown	Packed placement -> the decal showing it, for every placement shown this round.
stack_cache	Stack signature (stack_signature()) -> list(its key, its graffiti_art_glow_kind()), from the map file, while the load places its stacks: a stack it lists takes them without merging, as long as merges still give what they gave when the file was written (graffiti_merge_fingerprint()). Null otherwise.
start_cooldowns	Ckey -> the world.time from which that player may start another freehand session or paint job.
store	The map's graffiti file.
total_size	The estimated bytes `decoded` holds.
Procs
Initialize	Leaves the map's graffiti for the lobby, so loading it takes none of the server's startup: once every subsystem has initialized and the game reaches the lobby, it loads in the background (load_in_background()). Unit tests load it at once, as they read the registry straight away.
Recover	Takes over everything the subsystem being replaced kept, as the Master Controller restarts: the map's graffiti, the libraries and the painting under way.
Shutdown	Makes the final save when the world stops, for a reboot that skips the round-end save, and writes the library changes the write pacing still holds back. After the round-end save the map file isn't written again.
add_placement	Places a piece's art on a turf, on top of its stack, and queues the map file's write.
admin_area	Returns the area admin_rows() lists a placement under: its tile's, or its anchor's when it has none this round.
admin_changed	Forgets admin_rows()' orders and areas, as the placements or where they show changed.
admin_clear_all_maps	Deletes every placement on every map.
admin_clear_map	Deletes every placement on this map, and the painting under way on them (drop_work()), which may sleep.
admin_delete	Deletes placements by id, both halves of a wide piece alike, through remove_placements(), which may sleep.
admin_delete_ckey	Deletes one account's placements on this map through remove_placements(), which may sleep.
admin_delete_ckey_everywhere	Deletes one account's graffiti from every map and its graffiti library.
admin_edit_other_maps	Edits the graffiti file of every other map, beside this map's own in the same directory, and drops the art its placements no longer use, yielding between files. A file that can't be read, or has a version GRAFFITI_MAP_READ_VERSIONS doesn't list, is skipped with a log line. An older version's file keeps its version, as the edit only takes placements and art out.
admin_order	Returns every placement in one of admin_rows()' orders, sorting them again only after the placements changed.
admin_row	Returns admin_rows()' row for one placement.
admin_rows	Returns one page of the map's placements, shown and dormant alike, for the admin panel.
art_of	Returns a placement's art hash without unpacking it.
art_size	Returns the bytes an art counts against the map's art_byte_budget: its palette and grids.
build_sheets	Packs every shown stack into sprite sheet files, chunk by chunk, and shows each decal from its sheet.
check_anchor	Returns an anchor read from a file with only the fields its kind uses, as graffiti_anchor_for() writes them. One saved before windows took graffiti records `wall`, whether its surface is a wall, which is read as a wall or a floor.
check_placement	Returns a placement read from a map file in the form the registry keeps, with its painter's name cleaned again. Fields the registry doesn't keep, such as the names and descriptions placements once carried, are left out.
clear_file	Empties a map file's placements and art, for admin_edit_other_maps().
composite_turn	Whether it is a painter's turn to composite. Every painter's composites together take at most GRAFFITI_COMPOSITE_SHARE ms a second of game time, so under a dilating server they get less, and those waiting for room take it in the order they first asked (`composite_line`). Asking keeps the owner's place; running its composite gives it up, the owner taking itself out of the line, and so does not asking for GRAFFITI_COMPOSITE_LINE_GRACE, as an owner no longer due doesn't.
count_shown	Counts placements of an art in or out of those shown.
decoded_size	Estimates the bytes a decode holds: 8 a pixel for its indices, and for its glow unless it shares graffiti_unlit_glow()'s, and 40 a palette colour.
display	Shows a placement on top of its tile's stack.
drop_ckey	Drops one account's placements from a map file's placements, for admin_edit_other_maps().
drop_decoded	Lets the map load's decodes go: build_sheets() does once every sheet is drawn, and load_file()'s timer does should a runtime stop the load first.
drop_work	Ends what painters have under way on placements an admin deleted, keeping none of it: a freehand session or paint job painting them stops without an Unfinished piece, and an Unfinished piece left to resume on them is discarded, an offline owner's too, whose library is loaded for it and unloaded again. Yields between offline owners' libraries.
index_placement	Indexes a placement the registry has just taken: its info, and its place among its account's placements and art.
keep_decoded	Keeps a decode of an art or stack composite for the rest of the map's load, while the decodes kept stay within GRAFFITI_DECODE_BUDGET. Past it, that art is decoded again wherever it is needed, as it is outside the load.
keep_only_decoded	Lets the load's decodes go but those it still needs, counting what stays.
load_file	Loads a map file in place of whatever the registry held, keeping only what is valid and within the caps.
load_in_background	Loads the map's graffiti onto its tiles a share of each tick at a time (load_yield()), then starts noting who connects. Decals show their art once their chunk's sheet is drawn.
load_yield	Lets the background load go on in this tick until it has taken `load_share` percent of it, or the tick is full, then waits for the next, so the load spreads evenly over the ticks and the server never feels it. Each wait comes between two pieces of the load, the largest a tile's stack merged or one icon drawn.
lowest_unconnected	Returns the lowest-ranked placement whose owner isn't connected, as rank() orders them: the owner seen longest ago, then that owner's oldest placement, then the one earlier in `placements`. It reads each owner's index instead of ranking every placement.
make_room	Makes room on the map for a placement of an art, a new one or a placement's new art: past the map's caps, counting the account's own placements that its caps take, the lowest-ranked placement of an owner who isn't connected goes, until the art fits or nothing else can go. A placement never goes to make room for its own new art.
map_fits	Whether the map's caps, its art_byte_budget included, leave room for a new placement of an art once the placements the account's own caps take are gone.
on_client_connect	Notes when a player connected, and shows those of their dormant placements whose anchors resolve now, within the display budget.
on_pregame	Starts the background load as the game reaches the lobby.
own_evictions	Returns the account's own placements that its caps take for a new placement of an art: its oldest, while it keeps GRAFFITI_CKEY_PLACEMENT_CAP placements, or GRAFFITI_CKEY_UNIQUE_CAP arts and the art is new to it. Nothing is removed.
pids_by_ckey	Returns the placement ids each account owns among some placements, read while the index still holds them.
place_all	Shows each placement whose anchor resolves, best-ranked first while the display budget lasts, stacked on its tile in file order. The rest stay dormant: one that doesn't resolve counts a miss unless it is only waiting, and is dropped once it has missed GRAFFITI_MISS_LIMIT rounds in a row. The decals get their icons from build_sheets().
placement_turf	Returns the turf a placement's anchor names this round, for admin jumps and anchor checks. A shown placement's decal is in `shown`, which follows it even when its anchor no longer resolves to it.
queue_save	Writes the map file after GRAFFITI_SAVE_DEBOUNCE, with every change made meanwhile.
rank	Orders placements from the one to keep showing most to the first to evict: an owner who is connected first, then owners seen most recently, then the newest placement, then the one later in `candidates`.
reindex_placement	Moves a placement's index to its new packing, keeping its place among its account's placements.
release	Takes the placements of one space's anchors off their tiles and keeps them dormant, for graffiti_registry_release().
release_art	Drops one placement's hold on an art, and the art once nothing uses it, its icon and glow mask leaving the caches.
remove_placement	Removes a placement from the registry, and from its tile when it shows.
remove_placements	Removes placements from the registry at once, as an admin deletes them, ends the painting under way on them (drop_work()), then merges each tile they showed on again once, yielding between tiles: removing them one by one would merge a tile's whole stack for each. What else a tile stacks stays, in its order.
save_now	Writes the map file: the art and placements that last past this round, and when their owners were last seen. A map that has never had lasting graffiti gets no file. Nothing is written before the map's graffiti has loaded (`loaded`), while the registry may hold only part of the file, nor after the round-end save.
sheet_for	Returns the sheet a stack shows from.
spend_composite	Takes a composite's time out of composite_share, a session's last one and a paint job's finish included, which run whether or not there is room.
stack_keys	Returns what the map file caches of the stacks it keeps, so the next round's load shows them without merging them: each shown stack of several pieces, every piece of it kept, under its signature with its key and glow kind, beside the fingerprint of the merges that made them (graffiti_merge_fingerprint()).
tile_gone	Removes for good every placement a decal showed: its surface was cleaned, or is gone.
unindex_placement	Takes a placement the registry no longer holds out of the index.
unpack	Reads a packed placement.
update_placement_art	Gives a placement new art, as a freehand session or a paint job reveals more of its piece, and shows it. The art meets the caps a new placement's does (make_room()), its old art going from the placement, and when nothing can make room the placement keeps its old art.
vv_edit_var	Refuses admin edits of the library directory, which library files are written under.
wipe_for_test	Empties the registry for a test without writing anything: deletes every custom decal, clears the lists and the pending write, and unfreezes it. The store and the test settings stay.
write_sheet	Points a pack of stacks at their sheet file, writing it first unless an earlier round wrote the same one.

Var Details

var
admin_areas
– /list

Packed placement -> the area admin_rows() shows and sorts it under, until the placements change.

var
admin_orders
– /list

Sort -> every packed placement in that order, for admin_rows(), until the placements change.

var
anchor_resolvers
– /list

Anchor kind -> the /datum/callback a system registered to turn an anchor of that kind into a turf, or null.

var
art
– /list

Art hash -> the flat art, for every art a placement uses.

var
art_byte_budget

Most bytes of art the map keeps. Tests lower it.

var
art_bytes

The bytes of every art in art, as art_size() counts them.

var
art_icons
– /list

graffiti_art_hash() -> the icon graffiti_art_icon() drew of that art, up to GRAFFITI_ICON_CACHE of them.

var
art_refs
– /list

Art hash -> how many placements use it.

var
ckey_arts
– /list

Ckey -> art hash -> how many of its placements use it.

var
ckey_placements
– /list

Ckey -> its packed placements, in the order its own caps evict them: by "at", then as placements orders them.

var
composite_line
– /list

The editors and paint jobs waiting for composite_share, in the order they first asked, -> when each last asked.

var
composite_share

How many ms of composites may still run now, every painter's together. Below zero, they went over, and that is paid back first.

var
composite_share_at

When composite_share was last topped up.

var
decoded
– /list

Art hash -> graffiti_art_decode() of the arts and stack composites decoded while the map loads, for the load's merges and sheets, within GRAFFITI_DECODE_BUDGET. Null once build_sheets() has drawn them.

var
displayed_unique
– /list

Art hash -> how many shown placements use it, so its length counts the unique arts shown.

var
dormant
– /list

The packed placements not shown this round.

var
editors
– /list

Ckey -> that player's graffiti editor. A player has one at a time, opened through graffiti_editor_for().

var
frozen

Whether the round-end save has run, after which nothing is written.

var
glow_icons
– /list

graffiti_art_hash() -> the glow mask graffiti_glow_icon() drew of that art, up to GRAFFITI_ICON_CACHE of them.

var
libraries
– /list

Account ckey -> its loaded graffiti library.

var
library_revision

The last revision any graffiti library took. A library loaded again after a purge never repeats one an open window saw.

var
library_root

The directory library files go under. Tests point it at a scratch directory; admins can't edit it (vv_edit_var()).

var
load_resumed_at

TICK_USAGE when the background load last went on in a tick, which its share of the tick counts from.

var
load_share

Percent of each tick the load takes at most: GRAFFITI_LOAD_SHARE, or the whole tick in unit tests and benchmarks, which time the load's work rather than spread it.

var
loaded

Whether the map's graffiti has loaded, which it does in the background once the game reaches the lobby (load_in_background()): until then nothing is placed, saved or deleted by an admin.

var
loaded_templates
– /list

Map templates loaded this round on station levels, oldest first: list("id" = the template's map file, "x", "y", "z" = its low corner, "w", "h"). Recorded from SSmapping's init on, before this subsystem initializes.

var
map_path

Where the map's graffiti file is. Tests point it at a scratch file through load_file().

var
paint_jobs
– /list

Ckey -> that player's running paint job. A player runs one at a time.

var
placement_cap

Most placements the map keeps. Tests lower it.

var
placement_info
– /list

Packed placement -> list(ckey, art hash, "at", pid, "who", whether it lasts this round only), read through the GRAFFITI_INFO_* indices: what placement operations read of a placement without unpacking it.

var
placements
– /list

Every placement, packed, in the order they were placed, which each tile's stack follows.

var
save_failure_told

Whether the admins were told this round that the map file couldn't be written.

var
save_pending

The timer that will write the map file, while one is pending.

var
seen
– /list

Ckey -> when its owner last connected, as ten-digit unix seconds in text.

var
sheet_root

The directory every map's sheet files go under. Tests move it.

var
sheets
– /list

Stack key -> list(the sheet file's resource, whether it holds the stack's glow mask).

var
sheets_built

How many sheet files the last build_sheets() wrote rather than reused.

var
shown
– /list

Packed placement -> the decal showing it, for every placement shown this round.

var
stack_cache
– /list

Stack signature (stack_signature()) -> list(its key, its graffiti_art_glow_kind()), from the map file, while the load places its stacks: a stack it lists takes them without merging, as long as merges still give what they gave when the file was written (graffiti_merge_fingerprint()). Null otherwise.

var
start_cooldowns
– /list

Ckey -> the world.time from which that player may start another freehand session or paint job.

var
store
– /datum/json_savefile/custom_sprites/graffiti/map

The map's graffiti file.

var
total_size

The estimated bytes decoded holds.

Proc Details

↑
Initialize
()

Leaves the map's graffiti for the lobby, so loading it takes none of the server's startup: once every subsystem has initialized and the game reaches the lobby, it loads in the background (load_in_background()). Unit tests load it at once, as they read the registry straight away.

Returns:

SS_INIT_SUCCESS

Recover
()

Takes over everything the subsystem being replaced kept, as the Master Controller restarts: the map's graffiti, the libraries and the painting under way.

Shutdown
()

Makes the final save when the world stops, for a reboot that skips the round-end save, and writes the library changes the write pacing still holds back. After the round-end save the map file isn't written again.

proc
add_placement
(/turf/tile, /list/art, ckey, who, pid, half, /list/evicted)

Places a piece's art on a turf, on top of its stack, and queues the map file's write.

The map's caps are met first, counting the account's own placements that its caps take: past them the lowest-ranked placement of an owner who isn't connected goes, and when nothing else can go the new paint is refused with the account's own placements left alone. Only a placement that lands takes the account's own lowest-ranked ones, as many as its caps need. Off the station levels, in shuttles and in the holodeck, the placement lasts this round only.

Arguments:

tile: The wall, floor or window tile.
art: The art, GRAFFITI_WIDTH wide. The registry keeps a copy.
ckey: The painter's ckey.
who: The painter's character name.
pid: The placement's id. The two halves of a wide piece share one; null makes a new one.
half: 1 or 2 for the left or right half of a wide piece, else 0.
evicted: When given, filled with the ids of the account's own placements its caps took, for the painter to be told how many went.

Returns:

text: The packed placement, which is in placements.
text: Why it wasn't placed, safe to show the player. It is never in placements.

proc
admin_area
(packed)

Returns the area admin_rows() lists a placement under: its tile's, or its anchor's when it has none this round.

Arguments:

packed: The placement.

Returns:

text: The area's type, or "" when neither has one.

proc
admin_changed
()

Forgets admin_rows()' orders and areas, as the placements or where they show changed.

proc
admin_clear_all_maps
()

Deletes every placement on every map.

Returns:

number: How many placements were deleted, on every map.

proc
admin_clear_map
()

Deletes every placement on this map, and the painting under way on them (drop_work()), which may sleep.

Returns:

number: How many placements were deleted.

proc
admin_delete
(/list/pids)

Deletes placements by id, both halves of a wide piece alike, through remove_placements(), which may sleep.

Arguments:

pids: The ids.

Returns:

number: How many placements were deleted.

proc
admin_delete_ckey
(ckey)

Deletes one account's placements on this map through remove_placements(), which may sleep.

Arguments:

ckey: The account's ckey.

Returns:

number: How many placements were deleted.

proc
admin_delete_ckey_everywhere
(ckey)

Deletes one account's graffiti from every map and its graffiti library.

Arguments:

ckey: The account's ckey.

Returns:

number: How many placements were deleted, on every map.

proc
admin_edit_other_maps
(/datum/callback/edit)

Edits the graffiti file of every other map, beside this map's own in the same directory, and drops the art its placements no longer use, yielding between files. A file that can't be read, or has a version GRAFFITI_MAP_READ_VERSIONS doesn't list, is skipped with a log line. An older version's file keeps its version, as the edit only takes placements and art out.

Arguments:

edit: Called with each file's placements and art, both lists it may change.

Returns:

number: How many placements the edit took out of the files it wrote.

proc
admin_order
(sort)

Returns every placement in one of admin_rows()' orders, sorting them again only after the placements changed.

Arguments:

sort: "date" for the newest first, "ckey" or "area".

Returns:

list: The packed placements, which admin_orders keeps. Never change it.

proc
admin_row
(packed)

Returns admin_rows()' row for one placement.

Arguments:

packed: The placement.

Returns:

list: The row, as admin_rows() describes it.

proc
admin_rows
(search, sort, page)

Returns one page of the map's placements, shown and dormant alike, for the admin panel.

Arguments:

search: Text to find in a placement's ckey or its painter's character name, ignoring case, or null for every placement.
sort: "date" for the newest first, "ckey" or "area".
page: The page, from 1, of GRAFFITI_ADMIN_PAGE rows.

Returns:

list: "rows", each list("pid", "ckey", "who", "area", "x", "y", "z", "at", "state", "art") with "state" "shown", "dormant" or "round_only" and "art" the flat art for its thumbnail; and "total", the number of rows that match search on every page.

proc
art_of
(packed)

Returns a placement's art hash without unpacking it.

Arguments:

packed: A placement the registry holds.

Returns:

text: The hash.

proc
art_size
(/list/art)

Returns the bytes an art counts against the map's art_byte_budget: its palette and grids.

Arguments:

art: The art.

Returns:

number: The bytes.

proc
build_sheets
()

Packs every shown stack into sprite sheet files, chunk by chunk, and shows each decal from its sheet.

Decals are sorted by z level, 16-tile chunk and position, and each chunk's stacks are cut into sheets of up to GRAFFITI_SHEET_STATES, each stack in one sheet only. A sheet file is named by the hash of the stacks it holds and the alpha ceiling they are drawn at, so an unchanged chunk reuses the file of an earlier round, which clients have cached. Files no sheet uses are deleted, unless the map's graffiti isn't kept.

proc
check_anchor
(/list/anchor)

Returns an anchor read from a file with only the fields its kind uses, as graffiti_anchor_for() writes them. One saved before windows took graffiti records wall, whether its surface is a wall, which is read as a wall or a floor.

Arguments:

anchor: The anchor as the file has it.

Returns:

list: The anchor. One of a kind this module doesn't place is copied whole, with its surface, for its resolver to check.
null: A field is missing or has the wrong type.

proc
check_placement
(/list/entry, /list/known)

Returns a placement read from a map file in the form the registry keeps, with its painter's name cleaned again. Fields the registry doesn't keep, such as the names and descriptions placements once carried, are left out.

Arguments:

entry: The placement as the file has it.
known: Art hash -> art, for the file's valid art.

Returns:

list: The placement.
null: Its art isn't in known, or a field is missing or has the wrong type.

proc
clear_file
(/list/entries, /list/arts)

Empties a map file's placements and art, for admin_edit_other_maps().

Arguments:

entries: The file's placements.
arts: The file's art.

proc
composite_turn
(/datum/custom_sprite_work_owner/owner)

Whether it is a painter's turn to composite. Every painter's composites together take at most GRAFFITI_COMPOSITE_SHARE ms a second of game time, so under a dilating server they get less, and those waiting for room take it in the order they first asked (composite_line). Asking keeps the owner's place; running its composite gives it up, the owner taking itself out of the line, and so does not asking for GRAFFITI_COMPOSITE_LINE_GRACE, as an owner no longer due doesn't.

Arguments:

owner: The editor or paint job that would composite.

Returns:

TRUE/FALSE

proc
count_shown
(hash, change)

Counts placements of an art in or out of those shown.

Arguments:

hash: The art's hash.
change: How many more are shown, below 0 for fewer.

proc
decoded_size
(/list/record)

Estimates the bytes a decode holds: 8 a pixel for its indices, and for its glow unless it shares graffiti_unlit_glow()'s, and 40 a palette colour.

Arguments:

record: A graffiti_art_decode().

Returns:

number: The bytes.

proc
display
(packed, /turf/tile)

Shows a placement on top of its tile's stack.

Arguments:

packed: The placement.
tile: Its turf.

Returns:

TRUE/FALSE: Whether it shows. It doesn't when no decal can be made there.

proc
drop_ckey
(ckey, /list/entries, /list/arts)

Drops one account's placements from a map file's placements, for admin_edit_other_maps().

Arguments:

ckey: The account's ckey.
entries: The file's placements.
arts: The file's art.

proc
drop_decoded
()

Lets the map load's decodes go: build_sheets() does once every sheet is drawn, and load_file()'s timer does should a runtime stop the load first.

proc
drop_work
(/list/owners)

Ends what painters have under way on placements an admin deleted, keeping none of it: a freehand session or paint job painting them stops without an Unfinished piece, and an Unfinished piece left to resume on them is discarded, an offline owner's too, whose library is loaded for it and unloaded again. Yields between offline owners' libraries.

Arguments:

owners: pids_by_ckey() of the deleted placements.

proc
index_placement
(packed, /list/placement)

Indexes a placement the registry has just taken: its info, and its place among its account's placements and art.

Arguments:

packed: The placement.
placement: It unpacked.

proc
keep_decoded
(hash, /list/record, /list/art)

Keeps a decode of an art or stack composite for the rest of the map's load, while the decodes kept stay within GRAFFITI_DECODE_BUDGET. Past it, that art is decoded again wherever it is needed, as it is outside the load.

Arguments:

hash: The art's hash.
record: Its graffiti_art_decode().
art: The art.

proc
keep_only_decoded
(/list/keep)

Lets the load's decodes go but those it still needs, counting what stays.

Arguments:

keep: Art hash -> TRUE for the decodes to keep.

proc
load_file
(path)

Loads a map file in place of whatever the registry held, keeping only what is valid and within the caps.

Art that isn't valid one-tile art under its own hash, placements whose art is missing or whose fields have the wrong types, and the lowest-ranked placements and arts past the map caps are dropped and counted in one log line. A file that can't be read, or has a version GRAFFITI_MAP_READ_VERSIONS doesn't list, leaves the registry empty and unsaved, so the file stays for an admin. An older version's file is read as this version's, which its next save writes.

The current map's own file is named by graffiti_file_key() of its name. An admin-loaded custom map, whose name is whatever the admin typed, has no file: its store has no path, so nothing is read or written.

Arguments:

path: The file, or null for the current map's own.

proc
load_in_background
()

Loads the map's graffiti onto its tiles a share of each tick at a time (load_yield()), then starts noting who connects. Decals show their art once their chunk's sheet is drawn.

proc
load_yield
()

Lets the background load go on in this tick until it has taken load_share percent of it, or the tick is full, then waits for the next, so the load spreads evenly over the ticks and the server never feels it. Each wait comes between two pieces of the load, the largest a tile's stack merged or one icon drawn.

proc
lowest_unconnected
()

Returns the lowest-ranked placement whose owner isn't connected, as rank() orders them: the owner seen longest ago, then that owner's oldest placement, then the one earlier in placements. It reads each owner's index instead of ranking every placement.

Returns:

text: The packed placement.
null: Every owner is connected.

proc
make_room
(ckey, hash, size, replaced)

Makes room on the map for a placement of an art, a new one or a placement's new art: past the map's caps, counting the account's own placements that its caps take, the lowest-ranked placement of an owner who isn't connected goes, until the art fits or nothing else can go. A placement never goes to make room for its own new art.

Arguments:

ckey: The painter's ckey, which owns replaced.
hash: The art's hash.
size: The art's art_size().
replaced: The placement taking the art as its new art, or null for a new placement.

Returns:

list: The account's own placements its caps take (own_evictions()), for the caller to remove once the paint lands.
null: Nothing else can go, so the paint is refused.

proc
map_fits
(hash, size, /list/doomed)

Whether the map's caps, its art_byte_budget included, leave room for a new placement of an art once the placements the account's own caps take are gone.

Arguments:

hash: The art's hash.
size: The art's art_size().
doomed: The placements own_evictions() takes.

Returns:

TRUE/FALSE

proc
on_client_connect
(/datum/source, /client/player)

Notes when a player connected, and shows those of their dormant placements whose anchors resolve now, within the display budget.

Arguments:

source: SSdcs.
player: The client.

proc
on_pregame
(/datum/source)

Starts the background load as the game reaches the lobby.

Arguments:

source: SSticker.

proc
own_evictions
(ckey, hash, replaced)

Returns the account's own placements that its caps take for a new placement of an art: its oldest, while it keeps GRAFFITI_CKEY_PLACEMENT_CAP placements, or GRAFFITI_CKEY_UNIQUE_CAP arts and the art is new to it. Nothing is removed.

Arguments:

ckey: The account's ckey.
hash: The art's hash.
replaced: The account's placement taking the art as its new art, or null for a new placement. It is never taken, and its old art counts as gone from it.

Returns:

list: The packed placements, oldest first, which is how the account's index orders them.

proc
pids_by_ckey
(/list/packed_list)

Returns the placement ids each account owns among some placements, read while the index still holds them.

Arguments:

packed_list: The packed placements.

Returns:

list: Ckey -> pid -> TRUE.

proc
place_all
()

Shows each placement whose anchor resolves, best-ranked first while the display budget lasts, stacked on its tile in file order. The rest stay dormant: one that doesn't resolve counts a miss unless it is only waiting, and is dropped once it has missed GRAFFITI_MISS_LIMIT rounds in a row. The decals get their icons from build_sheets().

proc
placement_turf
(/list/placement)

Returns the turf a placement's anchor names this round, for admin jumps and anchor checks. A shown placement's decal is in shown, which follows it even when its anchor no longer resolves to it.

Arguments:

placement: The unpacked placement.

Returns:

turf: The turf.
null: Its anchor doesn't resolve.

proc
queue_save
()

Writes the map file after GRAFFITI_SAVE_DEBOUNCE, with every change made meanwhile.

proc
rank
(/list/candidates)

Orders placements from the one to keep showing most to the first to evict: an owner who is connected first, then owners seen most recently, then the newest placement, then the one later in candidates.

Arguments:

candidates: Packed placements the registry has indexed.

Returns:

list: The packed placements in that order, each associated with its sort key.

proc
reindex_placement
(packed, replacement, /list/placement)

Moves a placement's index to its new packing, keeping its place among its account's placements.

Arguments:

packed: Its old packing.
replacement: Its new packing.
placement: It unpacked, with its art now.

proc
release
(kind, key)

Takes the placements of one space's anchors off their tiles and keeps them dormant, for graffiti_registry_release().

Arguments:

kind: The anchor kind.
key: The anchors' owner.

proc
release_art
(hash)

Drops one placement's hold on an art, and the art once nothing uses it, its icon and glow mask leaving the caches.

Arguments:

hash: The art's hash.

proc
remove_placement
(packed, save, deferred)

Removes a placement from the registry, and from its tile when it shows.

Arguments:

packed: The placement.
save: Whether to queue the map file's write.
deferred: Whether to leave its tile's merge for the caller, which refreshes the tile once it has removed everything.

Returns:

TRUE/FALSE: Whether the registry held it.

proc
remove_placements
(/list/doomed)

Removes placements from the registry at once, as an admin deletes them, ends the painting under way on them (drop_work()), then merges each tile they showed on again once, yielding between tiles: removing them one by one would merge a tile's whole stack for each. What else a tile stacks stays, in its order.

Arguments:

doomed: The packed placements.

Returns:

number: How many of them the registry held.

proc
save_now
(final)

Writes the map file: the art and placements that last past this round, and when their owners were last seen. A map that has never had lasting graffiti gets no file. Nothing is written before the map's graffiti has loaded (loaded), while the registry may hold only part of the file, nor after the round-end save.

The file is joined from text, as json_encode() would write the same tree: each placement is kept packed already, and each art record is encoded as it is joined, so the registry holds no second copy of its art between saves.

Arguments:

final: Whether this is the round-end save.

proc
sheet_for
(stack_key)

Returns the sheet a stack shows from.

Arguments:

stack_key: The stack's key.

Returns:

list: list(the sheet file's resource, whether it holds the stack's glow mask as "[stack_key]_g").
null: No sheet holds the stack, such as one changed this round.

proc
spend_composite
(started)

Takes a composite's time out of composite_share, a session's last one and a paint job's finish included, which run whether or not there is room.

Arguments:

started: TICK_USAGE_REAL as the composite started.

proc
stack_keys
(/list/kept)

Returns what the map file caches of the stacks it keeps, so the next round's load shows them without merging them: each shown stack of several pieces, every piece of it kept, under its signature with its key and glow kind, beside the fingerprint of the merges that made them (graffiti_merge_fingerprint()).

Arguments:

kept: The packed placements the file keeps.

Returns:

list: list("print" = the fingerprint, "keys" = stack signature -> list(stack key, glow kind)).

proc
tile_gone
(/obj/effect/decal/cleanable/crayon/custom/decal)

Removes for good every placement a decal showed: its surface was cleaned, or is gone.

Arguments:

decal: The decal, being deleted.

proc
unindex_placement
(packed)

Takes a placement the registry no longer holds out of the index.

Arguments:

packed: The placement.

proc
unpack
(packed)

Reads a packed placement.

Arguments:

packed: The placement, as placements keeps it.

Returns:

list: The placement. Changing it changes nothing in the registry.

proc
update_placement_art
(packed, /list/art, /list/decoded, /list/evicted)

Gives a placement new art, as a freehand session or a paint job reveals more of its piece, and shows it. The art meets the caps a new placement's does (make_room()), its old art going from the placement, and when nothing can make room the placement keeps its old art.

Arguments:

packed: The placement.
art: Its new art, GRAFFITI_WIDTH wide. The registry keeps a copy.
decoded: The art's graffiti_art_decode(), when the caller has it, so its tile doesn't decode it again.
evicted: When given, filled with the ids of the account's own placements its caps took, for the painter to be told how many went.

Returns:

text: The placement packed again, which takes the old packing's place everywhere, or as it was when its art is unchanged. Keep it for the next update.
text: Why it kept its old art, safe to show the player. It is never in placements.
null: The placement is gone.

↑
vv_edit_var
(var_name, var_value)

Refuses admin edits of the library directory, which library files are written under.

Arguments:

var_name: The var.
var_value: Its new value.

Returns:

TRUE/FALSE: Whether the var was edited.

proc
wipe_for_test
()

Empties the registry for a test without writing anything: deletes every custom decal, clears the lists and the pending write, and unfreezes it. The store and the test settings stay.

proc
write_sheet
(/list/pack, map_name, /list/used)

Points a pack of stacks at their sheet file, writing it first unless an earlier round wrote the same one.

Arguments:

pack: Stack key -> the first decal showing it, in sheet order.
map_name: The map's name, which its sheet directory is named for.
used: Sheet file name -> TRUE for the files kept, which this adds to.

graffiti /datum/controller/subsystem/graffiti

Vars

Procs

Var Details

var admin_areas – /list

var admin_orders – /list

var anchor_resolvers – /list

var art – /list

var art_byte_budget

var art_bytes

var art_icons – /list

var art_refs – /list

var ckey_arts – /list

var ckey_placements – /list

var composite_line – /list

var composite_share

var composite_share_at

var decoded – /list

var displayed_unique – /list

var dormant – /list

var editors – /list

var frozen

var glow_icons – /list

var libraries – /list

var library_revision

var library_root

var load_resumed_at

var load_share

var loaded

var loaded_templates – /list

var map_path

var paint_jobs – /list

var placement_cap

var placement_info – /list

var placements – /list

var save_failure_told

var save_pending

var seen – /list

var sheet_root

var sheets – /list

var sheets_built

var shown – /list

var stack_cache – /list

var start_cooldowns – /list

var store – /datum/json_savefile/custom_sprites/graffiti/map

var total_size

Proc Details

↑Initialize()

Recover()

Shutdown()

proc add_placement(/turf/tile, /list/art, ckey, who, pid, half, /list/evicted)

proc admin_area(packed)

proc admin_changed()

proc admin_clear_all_maps()

proc admin_clear_map()

proc admin_delete(/list/pids)

proc admin_delete_ckey(ckey)

proc admin_delete_ckey_everywhere(ckey)

proc admin_edit_other_maps(/datum/callback/edit)

proc admin_order(sort)

proc admin_row(packed)

proc admin_rows(search, sort, page)

proc art_of(packed)

proc art_size(/list/art)

proc build_sheets()

proc check_anchor(/list/anchor)

proc check_placement(/list/entry, /list/known)

proc clear_file(/list/entries, /list/arts)

proc composite_turn(/datum/custom_sprite_work_owner/owner)

proc count_shown(hash, change)

proc decoded_size(/list/record)

proc display(packed, /turf/tile)

proc drop_ckey(ckey, /list/entries, /list/arts)

proc drop_decoded()

proc drop_work(/list/owners)

proc index_placement(packed, /list/placement)

proc keep_decoded(hash, /list/record, /list/art)

proc keep_only_decoded(/list/keep)

proc load_file(path)

proc load_in_background()

graffiti
/datum/controller/subsystem/graffiti

var
admin_areas
– /list

var
admin_orders
– /list

var
anchor_resolvers
– /list

var
art
– /list

var
art_byte_budget

var
art_bytes

var
art_icons
– /list

var
art_refs
– /list

var
ckey_arts
– /list

var
ckey_placements
– /list

var
composite_line
– /list

var
composite_share

var
composite_share_at

var
decoded
– /list

var
displayed_unique
– /list

var
dormant
– /list

var
editors
– /list

var
frozen

var
glow_icons
– /list

var
libraries
– /list

var
library_revision

var
library_root

var
load_resumed_at

var
load_share

var
loaded

var
loaded_templates
– /list

var
map_path

var
paint_jobs
– /list

var
placement_cap

var
placement_info
– /list

var
placements
– /list

var
save_failure_told

var
save_pending

var
seen
– /list

var
sheet_root

var
sheets
– /list

var
sheets_built

var
shown
– /list

var
stack_cache
– /list

var
start_cooldowns
– /list

var
store
– /datum/json_savefile/custom_sprites/graffiti/map

var
total_size

↑
Initialize
()

Recover
()

Shutdown
()

proc
add_placement
(/turf/tile, /list/art, ckey, who, pid, half, /list/evicted)

proc
admin_area
(packed)

proc
admin_changed
()

proc
admin_clear_all_maps
()

proc
admin_clear_map
()

proc
admin_delete
(/list/pids)

proc
admin_delete_ckey
(ckey)

proc
admin_delete_ckey_everywhere
(ckey)

proc
admin_edit_other_maps
(/datum/callback/edit)

proc
admin_order
(sort)

proc
admin_row
(packed)

proc
admin_rows
(search, sort, page)

proc
art_of
(packed)

proc
art_size
(/list/art)

proc
build_sheets
()

proc
check_anchor
(/list/anchor)

proc
check_placement
(/list/entry, /list/known)

proc
clear_file
(/list/entries, /list/arts)

proc
composite_turn
(/datum/custom_sprite_work_owner/owner)

proc
count_shown
(hash, change)

proc
decoded_size
(/list/record)

proc
display
(packed, /turf/tile)

proc
drop_ckey
(ckey, /list/entries, /list/arts)

proc
drop_decoded
()

proc
drop_work
(/list/owners)

proc
index_placement
(packed, /list/placement)

proc
keep_decoded
(hash, /list/record, /list/art)

proc
keep_only_decoded
(/list/keep)

proc
load_file
(path)

proc
load_in_background
()

proc
load_yield
()

proc
lowest_unconnected
()

proc
make_room
(ckey, hash, size, replaced)

proc
map_fits
(hash, size, /list/doomed)