From ee93ed05f9197308911b4e1b565de44865088a00 Mon Sep 17 00:00:00 2001 From: mochi Date: Tue, 30 Jun 2020 16:24:03 +0200 Subject: [PATCH] Document SSghost_spawns --- code/controllers/subsystem/ghost_spawns.dm | 66 +++++++++++++++++++--- 1 file changed, 57 insertions(+), 9 deletions(-) diff --git a/code/controllers/subsystem/ghost_spawns.dm b/code/controllers/subsystem/ghost_spawns.dm index 21088798a91..84282bf3176 100644 --- a/code/controllers/subsystem/ghost_spawns.dm +++ b/code/controllers/subsystem/ghost_spawns.dm @@ -6,10 +6,14 @@ SUBSYSTEM_DEF(ghost_spawns) runlevels = RUNLEVEL_GAME offline_implications = "Ghosts will no longer be able to respawn as event mobs (Terror, Blob, etc..). Shuttle call recommended." - var/list/datum/candidate_poll/currently_polling // List of polls currently ongoing, to be checked on next fire() - var/polls_active = FALSE // Whether there are active polls or not - var/total_polls = 0 // Number of polls performed since the start - var/datum/candidate_poll/next_poll_to_finish // The poll that's closest to finishing + /// List of polls currently ongoing, to be checked on next fire() + var/list/datum/candidate_poll/currently_polling + /// Whether there are active polls or not + var/polls_active = FALSE + /// Number of polls performed since the start + var/total_polls = 0 + /// The poll that's closest to finishing + var/datum/candidate_poll/next_poll_to_finish /datum/controller/subsystem/ghost_spawns/fire() if(!polls_active) @@ -22,8 +26,22 @@ SUBSYSTEM_DEF(ghost_spawns) if(P.time_left() <= 0) polling_finished(P) -// Use this proc (SSghost_spawns.poll_candidates) instead of /proc/pollCandidates to poll for candidates! -// Should NEVER be used in a proc that has waitfor set to FALSE/0 (due to #define UNTIL) +/** + * Polls for candidates with a question and a preview of the role + * + * This proc replaces /proc/pollCandidates. + * Should NEVER be used in a proc that has waitfor set to FALSE/0 (due to #define UNTIL) + * Arguments: + * * question - The question to ask to potential candidates + * * role - The role to poll for. Should be a ROLE_x enum. If set, potential candidates who aren't eligible will be ignored + * * antag_age_check - Whether to filter out potential candidates who don't have an old enough account + * * poll_time - How long to poll for in deciseconds + * * ignore_respawnability - Whether to ignore the player's respawnability + * * min_hours - The amount of hours needed for a potential candidate to be eligible + * * flash_window - Whether the poll should flash a potential candidate's game window + * * check_antaghud - Whether to filter out potential candidates who enabled AntagHUD + * * source - The atom or atom prototype to display as an icon in the alert + */ /datum/controller/subsystem/ghost_spawns/proc/poll_candidates(question = "Would you like to play a special role?", role, antag_age_check = FALSE, poll_time = 30 SECONDS, ignore_respawnability = FALSE, min_hours = 0, flash_window = TRUE, check_antaghud = TRUE, source) log_debug("Polling candidates [role ? "for [get_roletext(role)]" : "\"[question]\""] for [poll_time / 10] seconds") @@ -115,7 +133,17 @@ SUBSYSTEM_DEF(ghost_spawns) UNTIL(P.finished) return P.signed_up -// Whether an observer is eligible to be an event mob +/** + * Returns whether an observer is eligible to be an event mob + * + * Arguments: + * * M - The mob to check eligibility + * * role - The role to check eligibility for. Checks 1. the client has enabled the role 2. the account's age for this role if antag_age_check is TRUE + * * antag_age_check - Whether to check the account's age or not for the given role. + * * role_text - The role's clean text. Used for checking job bans to determine eligibility + * * min_hours - The amount of minimum hours the client needs before being eligible + * * check_antaghud - Whether to consider a client who enabled AntagHUD ineligible or not + */ /datum/controller/subsystem/ghost_spawns/proc/is_eligible(mob/M, role, antag_age_check, role_text, min_hours, check_antaghud) . = FALSE if(!M.key || !M.client) @@ -137,7 +165,13 @@ SUBSYSTEM_DEF(ghost_spawns) return TRUE -// Called when polling is finished for a /datum/candidate_poll +/** + * Called by the subsystem when a poll's timer runs out + * + * Can be called manually to finish a poll prematurely + * Arguments: + * * P - The poll to finish + */ /datum/controller/subsystem/ghost_spawns/proc/polling_finished(datum/candidate_poll/P) // Trim players who aren't eligible anymore var/len_pre_trim = length(P.signed_up) @@ -183,6 +217,15 @@ SUBSYSTEM_DEF(ghost_spawns) hash = copytext(md5("[question]_[role ? role : "0"]"), 1, 7) return ..() +/** + * Attempts to sign a (controlled) mob up + * + * Will fail if the mob is already signed up or the poll's timer ran out. + * Does not check for eligibility + * Arguments: + * * M - The (controlled) mob to sign up + * * silent - Whether no messages should appear or not. If not TRUE, signing up to this poll will also sign the mob up for identical polls + */ /datum/candidate_poll/proc/sign_up(mob/dead/observer/M, silent = FALSE) . = FALSE if(!istype(M) || !M.key || !M.client) @@ -208,7 +251,9 @@ SUBSYSTEM_DEF(ghost_spawns) return TRUE -// Deletes any candidates who may have disconnected from the list +/** + * Deletes any candidates who may have disconnected from the list + */ /datum/candidate_poll/proc/trim_candidates() listclearnulls(signed_up) for(var/mob in signed_up) @@ -216,5 +261,8 @@ SUBSYSTEM_DEF(ghost_spawns) if(!M.key || !M.client) signed_up -= M +/** + * Returns the time left for a poll + */ /datum/candidate_poll/proc/time_left() return duration - (world.time - time_started)