From af1777d7de364bf14e656dee07399cf764e8aea2 Mon Sep 17 00:00:00 2001 From: trollbreeder Date: Mon, 23 Mar 2020 12:27:36 +0100 Subject: [PATCH] Adds some documentation to species.dm (#50121) * Documentation on species vars, and roughly 40-50% of procs I can do no more of this. My mind is dead from boredom. * thought this proc was deprecated, apparantly its not cloning removal has permanentally scarred me * Updates speed and armor variable docs It wasn't made clear that armor was percentage based and speed was multiplicative in the documentation. This is now fixed. Also removes some whitespace. * Update code/modules/mob/living/carbon/human/species.dm Co-Authored-By: nemvar <47324920+nemvar@users.noreply.github.com> * Update code/modules/mob/living/carbon/human/species.dm Co-Authored-By: nemvar <47324920+nemvar@users.noreply.github.com> * Update code/modules/mob/living/carbon/human/species.dm Co-Authored-By: nemvar <47324920+nemvar@users.noreply.github.com> * Documentation updates with Qustinuss Mentions fixedmutcolor in hair_color Makes preferred food_type vars more clear that they are bitfields. toxic_food is not toxic, it's just more disgusting than disliked food Updates overlay var doc to mention that an empty string adds no damage overlays. * Defines uniqueness, also lastname docs change Updates generate name proc to have info on the unique argument Changes override this to set to false on lastname. Overriding is done with procs, not vars or arguments * updates proc docs to use double asterisk if this fails travis documentation i'm gonna be angery * i guess that makes sense updates copy properties proc with better docs * Part 2 of i guess this makes sense i should stop early commiting y'know * Update code/modules/mob/living/carbon/human/species.dm Co-Authored-By: Rohesie Co-authored-by: nemvar <47324920+nemvar@users.noreply.github.com> Co-authored-by: Rohesie --- .../mob/living/carbon/human/species.dm | 254 ++++++++++++++---- 1 file changed, 198 insertions(+), 56 deletions(-) diff --git a/code/modules/mob/living/carbon/human/species.dm b/code/modules/mob/living/carbon/human/species.dm index 5cec6a575b5..5ad72f33407 100644 --- a/code/modules/mob/living/carbon/human/species.dm +++ b/code/modules/mob/living/carbon/human/species.dm @@ -1,58 +1,110 @@ -// This code handles different species in the game. - GLOBAL_LIST_EMPTY(roundstart_races) +/** + * # species datum + * + * Datum that handles different species in the game. + * + * This datum handles species in the game, such as lizardpeople, mothmen, zombies, skeletons, etc. + * It is used in [carbon humans][mob/living/carbon/human] to determine various things about them, like their food preferences, if they have biological genders, their damage resistances, and more. + * + */ /datum/species - var/id // if the game needs to manually check your race to do something not included in a proc here, it will use this - var/limbs_id //this is used if you want to use a different species limb sprites. Mainly used for angels as they look like humans. - var/name // this is the fluff name. these will be left generic (such as 'Lizardperson' for the lizard race) so servers can change them to whatever - var/default_color = "#FFF" // if alien colors are disabled, this is the color that will be used by that race + ///If the game needs to manually check your race to do something not included in a proc here, it will use this. + var/id + //This is used if you want to use a different species' limb sprites. + var/limbs_id + ///This is the fluff name. They are displayed on health analyzers and in the character setup menu. Leave them generic for other servers to customize. + var/name + // Default color. If mutant colors are disabled, this is the color that will be used by that race. + var/default_color = "#FFF" - var/sexes = 1 // whether or not the race has sexual characteristics. at the moment this is only 0 for skeletons and shadows + ///Whether or not the race has sexual characteristics (biological genders). At the moment this is only FALSE for skeletons and shadows + var/sexes = TRUE + ///Clothing offsets. If a species has a different body than other species, you can offset clothing so they look less weird. var/list/offset_features = list(OFFSET_UNIFORM = list(0,0), OFFSET_ID = list(0,0), OFFSET_GLOVES = list(0,0), OFFSET_GLASSES = list(0,0), OFFSET_EARS = list(0,0), OFFSET_SHOES = list(0,0), OFFSET_S_STORE = list(0,0), OFFSET_FACEMASK = list(0,0), OFFSET_HEAD = list(0,0), OFFSET_FACE = list(0,0), OFFSET_BELT = list(0,0), OFFSET_BACK = list(0,0), OFFSET_SUIT = list(0,0), OFFSET_NECK = list(0,0)) - var/hair_color // this allows races to have specific hair colors... if null, it uses the H's hair/facial hair colors. if "mutcolor", it uses the H's mutant_color - var/hair_alpha = 255 // the alpha used by the hair. 255 is completely solid, 0 is transparent. + ///This allows races to have specific hair colors. If null, it uses the H's hair/facial hair colors. If "mutcolor", it uses the H's mutant_color. If "fixedmutcolor", it uses fixedmutcolor + var/hair_color + ///The alpha used by the hair. 255 is completely solid, 0 is invisible. + var/hair_alpha = 255 - var/use_skintones = 0 // does it use skintones or not? (spoiler alert this is only used by humans) - var/exotic_blood = "" // If your race wants to bleed something other than bog standard blood, change this to reagent id. - var/exotic_bloodtype = "" //If your race uses a non standard bloodtype (A+, O-, AB-, etc) - var/meat = /obj/item/reagent_containers/food/snacks/meat/slab/human //What the species drops on gibbing + ///Does the species use skintones or not? As of now only used by humans. + var/use_skintones = FALSE + ///If your race bleeds something other than bog standard blood, change this to reagent id. For example, ethereals bleed liquid electricity. + var/exotic_blood = "" + ///If your race uses a non standard bloodtype (A+, O-, AB-, etc). For example, lizards have L type blood. + var/exotic_bloodtype = "" + ///What the species drops when gibbed by a gibber machine. + var/meat = /obj/item/reagent_containers/food/snacks/meat/slab/human + ///What skin the species drops when gibbed by a gibber machine. var/skinned_type + ///Bitfield for food types that the species likes, giving them a mood boost. Lizards like meat, for example. var/liked_food = NONE + ///Bitfield for food types that the species dislikes, giving them disgust. Humans hate raw food, for example. var/disliked_food = GROSS + ///Bitfield for food types that the species absolutely hates, giving them even more disgust than disliked food. Meat is "toxic" to moths, for example. var/toxic_food = TOXIC - var/list/no_equip = list() // slots the race can't equip stuff to - var/nojumpsuit = 0 // this is sorta... weird. it basically lets you equip stuff that usually needs jumpsuits without one, like belts and pockets and ids - var/say_mod = "says" // affects the speech message + ///Inventory slots the race can't equip stuff to. Golems cannot wear jumpsuits, for example. + var/list/no_equip = list() + /// Allows the species to equip items that normally require a jumpsuit without having one equipped. Used by golems. + var/nojumpsuit = FALSE + ///Affects the speech message, for example: Motharula flutters, "My speech message is flutters!" + var/say_mod = "says" + ///What languages this species can understand and say. Use a [language holder datum][/datum/language_holder] in this var. var/species_language_holder = /datum/language_holder - var/list/default_features = list() // Default mutant bodyparts for this species. Don't forget to set one for every mutant bodypart you allow this species to have. - var/list/mutant_bodyparts = list() // Visible CURRENT bodyparts that are unique to a species. DO NOT USE THIS AS A LIST OF ALL POSSIBLE BODYPARTS AS IT WILL FUCK SHIT UP! Changes to this list for non-species specific bodyparts (ie cat ears and tails) should be assigned at organ level if possible. Layer hiding is handled by handle_mutant_bodyparts() below. - var/list/mutant_organs = list() //Internal organs that are unique to this race. - var/speedmod = 0 // this affects the race's speed. positive numbers make it move slower, negative numbers make it move faster - var/armor = 0 // overall defense for the race... or less defense, if it's negative. - var/brutemod = 1 // multiplier for brute damage - var/burnmod = 1 // multiplier for burn damage - var/coldmod = 1 // multiplier for cold damage - var/heatmod = 1 // multiplier for heat damage - var/stunmod = 1 // multiplier for stun duration - var/attack_type = BRUTE //Type of damage attack does - var/punchdamagelow = 1 //lowest possible punch damage. if this is set to 0, punches will always miss - var/punchdamagehigh = 10 //highest possible punch damage - var/punchstunthreshold = 10//damage at which punches from this race will stun //yes it should be to the attacked race but it's not useful that way even if it's logical - var/siemens_coeff = 1 //base electrocution coefficient - var/damage_overlay_type = "human" //what kind of damage overlays (if any) appear on our species when wounded? - var/fixed_mut_color = "" //to use MUTCOLOR with a fixed color that's independent of dna.feature["mcolor"] - var/inert_mutation = DWARFISM //special mutation that can be found in the genepool. Dont leave empty or changing species will be a headache - var/deathsound //used to set the mobs deathsound on species change - var/list/special_step_sounds //Sounds to override barefeet walkng - var/grab_sound //Special sound for grabbing - var/datum/outfit/outfit_important_for_life /// A path to an outfit that is important for species life e.g. plasmaman outfit + /// Default mutant bodyparts for this species, like horns. Don't forget to set one for every mutant bodypart you allow this species to have. + var/list/default_features = list() + /// Visible CURRENT bodyparts that are unique to a species. DO NOT USE THIS AS A LIST OF ALL POSSIBLE BODYPARTS AS IT WILL FUCK SHIT UP! Changes to this list for non-species specific bodyparts (ie cat ears and tails) should be assigned at organ level if possible. Layer hiding is handled by [datum/species/handle_mutant_bodyparts()] below. + var/list/mutant_bodyparts = list() + ///Internal organs that are unique to this race, like a tail. + var/list/mutant_organs = list() + ///Multiplier for the race's speed. Positive numbers make it move slower, negative numbers make it move faster. + var/speedmod = 0 + ///Percentage modifier for overall defense of the race, or less defense, if it's negative. + var/armor = 0 + ///multiplier for brute damage + var/brutemod = 1 + ///multiplier for burn damage + var/burnmod = 1 + ///multiplier for damage from cold temperature + var/coldmod = 1 + ///multiplier for damage from hot temperature + var/heatmod = 1 + ///multiplier for stun durations + var/stunmod = 1 + ///Type of damage attack does. Ethereals attack with burn damage for example. + var/attack_type = BRUTE + ///Lowest possible punch damage this species can give. If this is set to 0, punches will always miss. + var/punchdamagelow = 1 + ///Highest possible punch damage this species can give. + var/punchdamagehigh = 10 + ///Damage at which punches from this race will stun + var/punchstunthreshold = 10 //yes it should be to the attacked race but it's not useful that way even if it's logical + ///Base electrocution coefficient. Basically a multiplier for damage from electrocutions. + var/siemens_coeff = 1 + ///What kind of damage overlays (if any) appear on our species when wounded? If this is "", does not add an overlay. + var/damage_overlay_type = "human" + ///To use MUTCOLOR with a fixed color that's independent of the mcolor feature in DNA. + var/fixed_mut_color = "" + ///Special mutation that can be found in the genepool exclusively in this species. Dont leave empty or changing species will be a headache + var/inert_mutation = DWARFISM + ///Used to set the mob's deathsound upon species change + var/deathsound + ///Sounds to override barefeet walking + var/list/special_step_sounds + ///Special sound for grabbing + var/grab_sound + /// A path to an outfit that is important for species life e.g. plasmaman outfit + var/datum/outfit/outfit_important_for_life - var/flying_species = FALSE //is a flying species, just a check for some things - var/datum/action/innate/flight/fly //the actual flying ability given to flying species - var/wings_icon = "Angel" //the icon used for the wings + ///Is this species a flying species? Used as an easy check for some things + var/flying_species = FALSE + ///The actual flying ability given to flying species + var/datum/action/innate/flight/fly + ///The icon used for the wings + var/wings_icon = "Angel" /// The natural temperature for a body var/bodytemp_normal = BODYTEMP_NORMAL @@ -63,40 +115,52 @@ GLOBAL_LIST_EMPTY(roundstart_races) /// The body temperature limit the body can take before it starts taking damage from cold. var/bodytemp_cold_damage_limit = BODYTEMP_COLD_DAMAGE_LIMIT - // species-only traits. Can be found in DNA.dm + ///Species-only traits. Can be found in [code/_DEFINES/DNA.dm] var/list/species_traits = list() - // generic traits tied to having the species + ///Generic traits tied to having the species. var/list/inherent_traits = list() + /// List of biotypes the mob belongs to. Used by diseases. var/inherent_biotypes = MOB_ORGANIC|MOB_HUMANOID ///List of factions the mob gain upon gaining this species. var/list/inherent_factions - var/attack_verb = "punch" // punch-specific attack verb + ///Punch-specific attack verb. + var/attack_verb = "punch" + /// var/sound/attack_sound = 'sound/weapons/punch1.ogg' var/sound/miss_sound = 'sound/weapons/punchmiss.ogg' - //Breathing! Most changes are in mutantlungs, though + ///What gas does this species breathe? Used by suffocation screen alerts, most of actual gas breathing is handled by mutantlungs. See [life.dm][code/modules/mob/living/carbon/human/life.dm] var/breathid = "o2" //Do NOT remove by setting to null. use OR make a RESPECTIVE TRAIT (removing stomach? add the NOSTOMACH trait to your species) //why does it work this way? because traits also disable the downsides of not having an organ, removing organs but not having the trait will make your species die + + ///Replaces default brain with a different organ var/obj/item/organ/brain/mutantbrain = /obj/item/organ/brain + ///Replaces default heart with a different organ var/obj/item/organ/heart/mutantheart = /obj/item/organ/heart + ///Replaces default lungs with a different organ var/obj/item/organ/lungs/mutantlungs = /obj/item/organ/lungs + ///Replaces default eyes with a different organ var/obj/item/organ/eyes/mutanteyes = /obj/item/organ/eyes + ///Replaces default ears with a different organ var/obj/item/organ/ears/mutantears = /obj/item/organ/ears + ///Replaces default tongue with a different organ var/obj/item/organ/tongue/mutanttongue = /obj/item/organ/tongue + ///Replaces default liver with a different organ var/obj/item/organ/liver/mutantliver = /obj/item/organ/liver + ///Replaces default stomach with a different organ var/obj/item/organ/stomach/mutantstomach = /obj/item/organ/stomach + ///Replaces default appendix with a different organ. var/obj/item/organ/appendix/mutantappendix = /obj/item/organ/appendix - //only an honorary mutantthing because not an organ and not loaded in the same way, you've been warned to do your research + ///Forces an item into this species' hands. Only an honorary mutantthing because this is not an organ and not loaded in the same way, you've been warned to do your research. var/obj/item/mutanthands + ///Allows the species to not give a single F about gravity. Used by wings. var/override_float = FALSE - //Bitflag that controls what in game ways can select this species as a spawnable source - //Think magic mirror and pride mirror, slime extract, ERT etc, see defines - //in __DEFINES/mobs.dm, defaults to NONE, so people actually have to think about it + ///Bitflag that controls what in game ways something can select this species as a spawnable source, such as magic mirrors. See [mob defines][code/_DEFINES/mobs.dm] for possible sources. var/changesource_flags = NONE /////////// @@ -110,7 +174,12 @@ GLOBAL_LIST_EMPTY(roundstart_races) limbs_id = id ..() - +/** + * Generates species available to choose in character setup at roundstart + * + * This proc generates which species are available to pick from in character setup. + * If there are no available roundstart species, defaults to human. + */ /proc/generate_selectable_species() for(var/I in subtypesof(/datum/species)) var/datum/species/S = new I @@ -120,11 +189,26 @@ GLOBAL_LIST_EMPTY(roundstart_races) if(!GLOB.roundstart_races.len) GLOB.roundstart_races += "human" +/** + * Checks if a species is eligible to be picked at roundstart. + * + * Checks the config to see if this species is allowed to be picked in the character setup menu. + * Used by [proc/generate_selectable_species]. + */ /datum/species/proc/check_roundstart_eligible() if(id in (CONFIG_GET(keyed_list/roundstart_races))) return TRUE return FALSE +/** + * Generates a random name for a carbon. + * + * This generates a random unique name based on a human's species and gender. + * Arguments: + * * gender - The gender that the name should adhere to. Use MALE for male names, use anything else for female names. + * * unique - If true, ensures that this new name is not a duplicate of anyone else's name currently on the station. + * * lastname - Does this species' naming system adhere to the last name system? Set to false if it doesn't. + */ /datum/species/proc/random_name(gender,unique,lastname) if(unique) return random_unique_name(gender) @@ -142,11 +226,24 @@ GLOBAL_LIST_EMPTY(roundstart_races) return randname -//Called when cloning, copies some vars that should be kept +/** + * Copies some vars and properties over that should be kept when creating a copy of this species. + * + * Used by slimepeople to copy themselves, and by the DNA datum to hardset DNA to a species + * Arguments: + * * old_species - The species that the carbon used to be before copying + */ /datum/species/proc/copy_properties_from(datum/species/old_species) return -//Please override this locally if you want to define when what species qualifies for what rank if human authority is enforced. +/** + * Checks if this carbon is allowed to be a certain job or rank. + * + * Override this locally if you want to define when this species qualifies for what rank if human authority is enforced. + * Arguments: + * * rank - Rank to be tested. + * * features - Features of a species that factors into rank qualifications, like a human with cat ears being unable to join command positions. + */ /datum/species/proc/qualifies_for_rank(rank, list/features) if(rank in GLOB.command_positions) return 0 @@ -159,10 +256,10 @@ GLOBAL_LIST_EMPTY(roundstart_races) * takes all organ slots, removes organs a species should not have, adds organs a species should have. * can use replace_current to refresh all organs, creating an entirely new set. * Arguments: - * C - carbon, the owner of the species datum AKA whoever we're regenerating organs in - * old_species - datum, used when regenerate organs is called in a switching species to remove old mutant organs. - * replace_current - boolean, forces all old organs to get deleted whether or not they pass the species' ability to keep that organ - * excluded_zones - list, add zone defines to block organs inside of the zones from getting handled. see headless mutation for an example + * * C - carbon, the owner of the species datum AKA whoever we're regenerating organs in + * * old_species - datum, used when regenerate organs is called in a switching species to remove old mutant organs. + * * replace_current - boolean, forces all old organs to get deleted whether or not they pass the species' ability to keep that organ + * * excluded_zones - list, add zone defines to block organs inside of the zones from getting handled. see headless mutation for an example */ /datum/species/proc/regenerate_organs(mob/living/carbon/C,datum/species/old_species,replace_current=TRUE,list/excluded_zones) //what should be put in if there is no mutantorgan (brains handled seperately) @@ -207,6 +304,16 @@ GLOBAL_LIST_EMPTY(roundstart_races) var/obj/item/organ/missed = new thing() missed.Insert(C, TRUE, FALSE) +/** + * Proc called when a carbon becomes this species. + * + * This sets up and adds/changes/removes things, qualities, abilities, and traits so that the transformation is as smooth and bugfree as possible. + * Produces a [COMSIG_SPECIES_GAIN] signal. + * Arguments: + * * C - Carbon, this is whoever became the new species. + * * old_species - The species that the carbon used to be before becoming this race, used for regenerating organs. + * * pref_load - Preferences to be loaded from character setup, loads in preferred mutant things like bodyparts, digilegs, skin color, etc. + */ /datum/species/proc/on_species_gain(mob/living/carbon/C, datum/species/old_species, pref_load) // Drop the items the new species can't wear if((AGENDER in species_traits)) @@ -274,6 +381,16 @@ GLOBAL_LIST_EMPTY(roundstart_races) SEND_SIGNAL(C, COMSIG_SPECIES_GAIN, src, old_species) +/** + * Proc called when a carbon is no longer this species. + * + * This sets up and adds/changes/removes things, qualities, abilities, and traits so that the transformation is as smooth and bugfree as possible. + * Produces a [COMSIG_SPECIES_LOSS] signal. + * Arguments: + * * C - Carbon, this is whoever lost this species. + * * new_species - The new species that the carbon became, used for genetics mutations. + * * pref_load - Preferences to be loaded from character setup, loads in preferred mutant things like bodyparts, digilegs, skin color, etc. + */ /datum/species/proc/on_species_loss(mob/living/carbon/human/C, datum/species/new_species, pref_load) if(C.dna.species.exotic_bloodtype) C.dna.blood_type = random_blood_type() @@ -309,6 +426,14 @@ GLOBAL_LIST_EMPTY(roundstart_races) SEND_SIGNAL(C, COMSIG_SPECIES_LOSS, src) +/** + * Handles hair icons and dynamic hair. + * + * Handles hiding hair with clothing, hair layers, losing hair due to husking or augmented heads, facial hair, head hair, and hair styles. + * Arguments: + * * H - Human, whoever we're handling the hair for + * * forced_colour - The colour of hair we're forcing on this human. Leave null to not change. Mind the british spelling! + */ /datum/species/proc/handle_hair(mob/living/carbon/human/H, forced_colour) H.remove_overlay(HAIR_LAYER) var/obj/item/bodypart/head/HD = H.get_bodypart(BODY_ZONE_HEAD) @@ -456,6 +581,14 @@ GLOBAL_LIST_EMPTY(roundstart_races) H.apply_overlay(HAIR_LAYER) +/** + * Handles the body of a human + * + * Handles lipstick, having no eyes, eye color, undergarnments like underwear, undershirts, and socks, and body layers. + * Calls [handle_mutant_bodyparts][/datum/species/proc/handle_mutant_bodyparts] + * Arguments: + * * H - Human, whoever we're handling the body for + */ /datum/species/proc/handle_body(mob/living/carbon/human/H) H.remove_overlay(BODY_LAYER) @@ -518,6 +651,15 @@ GLOBAL_LIST_EMPTY(roundstart_races) H.apply_overlay(BODY_LAYER) handle_mutant_bodyparts(H) +/** + * Handles the mutant bodyparts of a human + * + * Handles the adding and displaying of, layers, colors, and overlays of mutant bodyparts and accessories. + * Handles digitigrade leg displaying and squishing. + * Arguments: + * * H - Human, whoever we're handling the body for + * * forced_colour - The forced color of an accessory. Leave null to use mutant color. + */ /datum/species/proc/handle_mutant_bodyparts(mob/living/carbon/human/H, forced_colour) var/list/bodyparts_to_add = mutant_bodyparts.Copy() var/list/relevent_layers = list(BODY_BEHIND_LAYER, BODY_ADJ_LAYER, BODY_FRONT_LAYER)