graffiti_library

One account's graffiti library: up to GRAFFITI_LIBRARY_CAP pieces and the Unfinished slot, kept in one JSON file under SSgraffiti.library_root. Get it with graffiti_library().

Every change is written through and undone when the write fails, so the library holds what its file doesn't only while a change the server made waits for the write pacing (save()). A write the file holds stands even when its backup couldn't be refreshed after it, which the next save does. It unloads as its owner disconnects, or, while an editor session, a paint job or a held write still needs it, once they end (graffiti_library_unload()).

Vars
ckey	The account's ckey.
next_id	The number in the next new piece's id, "g[next_id]".
pieces	Piece id -> list("piece" = canonical piece, "created", "updated", "thumb" = its flattened art), oldest first. Entries are replaced, never changed.
revealed	What unfinished_entry() last flattened of a stopped paint job: list(piece, progress, the art revealed). The slot's piece is replaced, never changed, so a piece and a progress always reveal the same art.
revision	Its state's number, from SSgraffiti.library_revision and new with each change, so a window that shows it knows to send it again.
store	The library's file.
unfinished	The last interrupted or unsaved piece, list("piece", "resume", "created", "thumb"), or null.
unwritten	snapshot() of the library as its file holds it, while changes wait for write_timer.
write_timer	The timer that writes the changes held back by the write pacing, while one is pending.
Procs
New	Loads an account's library from its file.
delete_piece	Deletes a saved piece.
discard_unfinished	Empties the Unfinished slot.
entries	Returns the saved pieces as the spraycan's Custom Graffiti tab lists them, newest first.
entry_data	Returns one piece as the Custom Graffiti tab lists it.
export_text	Returns a saved piece as the text Export writes.
import_piece	Imports a piece as a new piece. It must pass graffiti_validate_piece() as given, its `format` and `version` included.
keep_unfinished	Moves the Unfinished piece into the library as a new piece.
piece	Returns a saved piece.
put	Stores a canonical piece in `pieces` without writing the file.
rename_piece	Renames a saved piece and sets its description, as the Custom Graffiti tab edits them. Its art stays as it is.
save	Writes the library to its file, or deletes the file once the library holds no pieces and no Unfinished piece, and paces the account's next write by how long this one took (graffiti_library_paced()).
save_piece	Saves a piece into the library, as a new piece or over one it holds.
set_unfinished	Puts a piece in the Unfinished slot, replacing what it held.
snapshot	Returns the library's state, for save() to put back when a change can't be written.
unfinished_entry	Returns the Unfinished slot as the Custom Graffiti tab shows it.
write_held	Writes the changes the write pacing held back, as write_timer fires, then unloads the library if its owner disconnected meanwhile (graffiti_library_unload()). A library no longer loaded, as after an admin purge, writes nothing.

Var Details

var
ckey

The account's ckey.

var
next_id

The number in the next new piece's id, "g[next_id]".

var
pieces
– /list

Piece id -> list("piece" = canonical piece, "created", "updated", "thumb" = its flattened art), oldest first. Entries are replaced, never changed.

var
revealed
– /list

What unfinished_entry() last flattened of a stopped paint job: list(piece, progress, the art revealed). The slot's piece is replaced, never changed, so a piece and a progress always reveal the same art.

var
revision

Its state's number, from SSgraffiti.library_revision and new with each change, so a window that shows it knows to send it again.

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

The library's file.

var
unfinished
– /list

The last interrupted or unsaved piece, list("piece", "resume", "created", "thumb"), or null.

var
unwritten
– /list

snapshot() of the library as its file holds it, while changes wait for write_timer.

var
write_timer

The timer that writes the changes held back by the write pacing, while one is pending.

Proc Details

New
(ckey)

Loads an account's library from its file.

Every stored piece is validated again, and one that fails is dropped with a log line, as are pieces past GRAFFITI_LIBRARY_CAP. When the file can't be read at all, such as one over GRAFFITI_LIBRARY_MAX_BYTES, the library starts empty and its store refuses every write, so the file stays for an admin to look at.

Arguments:

ckey: The account's ckey.

proc
delete_piece
(id)

Deletes a saved piece.

Arguments:

id: The piece's id.

Returns:

TRUE/FALSE: Whether it was deleted. It isn't when no piece has that id or the file couldn't be written.

proc
discard_unfinished
(hold)

Empties the Unfinished slot.

Arguments:

hold: Whether the server makes the change, as a finished paint job does, so that save() holds it back while the write pacing runs rather than writing at once.

Returns:

TRUE/FALSE: Whether a piece was discarded. None is when the slot is empty or the file couldn't be written.

proc
entries
()

Returns the saved pieces as the spraycan's Custom Graffiti tab lists them, newest first.

Returns:

list: One entry_data() list per piece, by creation time. Among pieces made in the same second, the one added last comes first.

proc
entry_data
(id, /list/entry)

Returns one piece as the Custom Graffiti tab lists it.

Arguments:

id: The piece's id, or null for the Unfinished slot.
entry: Its entry in pieces, or unfinished.

Returns:

list: id, name, description, width, created, updated, glow (whether any layer glows), layers (how many) and thumb, the flattened art.

proc
export_text
(id)

Returns a saved piece as the text Export writes.

Arguments:

id: The piece's id.

Returns:

text: The piece's JSON, from graffiti_encode_piece().
null: No piece has that id.

proc
import_piece
(raw)

Imports a piece as a new piece. It must pass graffiti_validate_piece() as given, its format and version included.

Arguments:

raw: The piece's JSON text, as Export writes it, or that text decoded.

Returns:

text: The new piece's id, a key of pieces.
text: Why it was refused, safe to show the player. It never repeats the piece's text.

proc
keep_unfinished
()

Moves the Unfinished piece into the library as a new piece.

Returns:

text: The new piece's id, a key of pieces.
text: Why it wasn't moved, safe to show the player. The slot keeps its piece.

proc
piece
(id)

Returns a saved piece.

Arguments:

id: The piece's id.

Returns:

list: The canonical piece. Never change it.
null: No piece has that id.

proc
put
(/list/piece, id, /list/art)

Stores a canonical piece in pieces without writing the file.

Arguments:

piece: The canonical piece.
id: The piece it replaces, which keeps its id and creation time, or null for a new piece.
art: The piece's flattened art, when the caller has it.

Returns:

text: The piece's id.

proc
rename_piece
(id, name, description)

Renames a saved piece and sets its description, as the Custom Graffiti tab edits them. Its art stays as it is.

Arguments:

id: The piece's id.
name: Its new name, cleaned as names are kept, or "Untitled" when nothing is left of it.
description: Its new description, cleaned as descriptions are kept.

Returns:

TRUE: The piece has that name and description, written now or already.
text: Why it wasn't renamed, safe to show the player.

proc
save
(/list/previous, hold)

Writes the library to its file, or deletes the file once the library holds no pieces and no Unfinished piece, and paces the account's next write by how long this one took (graffiti_library_paced()).

A change the server makes is never refused for the pacing: while the account's last write still paces the next, it is held back, and write_timer writes it once the pacing allows, with whatever else changed meanwhile. Any write takes the changes held so far with it.

Arguments:

previous: snapshot()'s state from before the change being written, put back when the write fails.
hold: Whether to hold the change back while the pacing runs rather than write it at once.

Returns:

TRUE/FALSE: Whether the file holds the library, or will once the change held back is written.

proc
save_piece
(/list/piece, id)

Saves a piece into the library, as a new piece or over one it holds.

Arguments:

piece: The piece, such as the editor serializes it. It is validated and cleaned again.
id: The piece to replace. A new piece is made when it is null or no longer in the library.

Returns:

text: The piece's id, a key of pieces.
text: Why nothing was saved, safe to show the player. It is never a key of pieces.

proc
set_unfinished
(/list/piece, /list/resume, hold)

Puts a piece in the Unfinished slot, replacing what it held.

Arguments:

piece: The piece, such as the editor serializes it. It is validated and cleaned again.
resume: What a stopped paint job or freehand session resumes from, list("map", "anchor", "pid", "progress", "width"), or null. The library keeps a copy and never reads it.
hold: Whether the server makes the change, as a session or paint job ends, so that save() holds it back while the write pacing runs rather than writing at once.

Returns:

null: The slot holds the piece.
text: Why it doesn't, safe to show the player.

proc
snapshot
()

Returns the library's state, for save() to put back when a change can't be written.

Returns:

list: A copy of pieces, with unfinished and next_id.

proc
unfinished_entry
()

Returns the Unfinished slot as the Custom Graffiti tab shows it.

Returns:

list: entry_data()'s fields with a null id, plus resume, as set_unfinished() was given it, progress, its "progress" (null without resume data), and revealed, the flattened art of what a stopped paint job revealed (null for anything else).
null: The slot is empty.

proc
write_held
()

Writes the changes the write pacing held back, as write_timer fires, then unloads the library if its owner disconnected meanwhile (graffiti_library_unload()). A library no longer loaded, as after an admin purge, writes nothing.

graffiti_library /datum/graffiti_library

Vars

Procs

Var Details

var ckey

var next_id

var pieces – /list

var revealed – /list

var revision

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

var unfinished – /list

var unwritten – /list

var write_timer

Proc Details

New(ckey)

proc delete_piece(id)

proc discard_unfinished(hold)

proc entries()

proc entry_data(id, /list/entry)

proc export_text(id)

proc import_piece(raw)

proc keep_unfinished()

proc piece(id)

proc put(/list/piece, id, /list/art)

proc rename_piece(id, name, description)

proc save(/list/previous, hold)

proc save_piece(/list/piece, id)

proc set_unfinished(/list/piece, /list/resume, hold)

proc snapshot()

proc unfinished_entry()

proc write_held()

graffiti_library
/datum/graffiti_library

var
ckey

var
next_id

var
pieces
– /list

var
revealed
– /list

var
revision

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

var
unfinished
– /list

var
unwritten
– /list

var
write_timer

New
(ckey)

proc
delete_piece
(id)

proc
discard_unfinished
(hold)

proc
entries
()

proc
entry_data
(id, /list/entry)

proc
export_text
(id)

proc
import_piece
(raw)

proc
keep_unfinished
()

proc
piece
(id)

proc
put
(/list/piece, id, /list/art)

proc
rename_piece
(id, name, description)

proc
save
(/list/previous, hold)

proc
save_piece
(/list/piece, id)

proc
set_unfinished
(/list/piece, /list/resume, hold)

proc
snapshot
()

proc
unfinished_entry
()

proc
write_held
()