atom

The base type for nearly all physical objects in SS13

Lots and lots of functionality lives here, although in general we are striving to move as much as possible to the components/elements system

Var Details

add_overlays

a very temporary list of overlays to add

article

If non-null, overrides a/an/some in all cases

atom_colours

used to store the different colors on an atom

its inherent color, the colored paint applied on it, special color effect etc...

base_icon_state

Used for changing icon states for different base sprites.

base_pixel_x

Default X pixel offset

base_pixel_y

Default Y pixel offset

bottom_left_corner

Smoothing variable

bottom_right_corner

Smoothing variable

buckle_message_cooldown

Cooldown tick timer for buckle messages

canSmoothWith

List of smoothing groups this atom can smooth with. If this is null and atom is smooth, it smooths only with itself.

chat_color

Last color calculated for the the chatmessage overlays

chat_color_darkened

A luminescence-shifted value of the last color calculated for chatmessage overlays

chat_color_name

Last name used to calculate a color for the chatmessage overlays

connector_icon

The icon file of the connector to use when smoothing. Use of connectors requires the smoothing flags SMOOTH_BITMASK and SMOOTH_CONNECTORS.

connector_icon_state

The icon state prefix used for connectors. Equivalent to the base_icon_state.

connector_junction

The current connector junction, saved to stop overlay changes if none are necessary.

connector_overlay

The current connector overlay appearance. Saved so that it can be cut when necessary.

connector_strict_typing

If true, the typecache constructed for no_connector_typecache will NOT include subtypes.

custom_materials

The custom materials this atom is made of, used by a lot of things like furniture, walls, and floors (if I finish the functionality, that is.)

custom_premium_price

Economy cost of item in premium vendor

custom_price

Economy cost of item

demo_last_appearance

Last appearance of the atom for demo saving purposes

explosion_block

Value used to increment ex_act() if reactionary_explosions is on

fingerprintslast

Last fingerprints to touch this atom

flags_1

First atom flags var

hitsound_type

Wanted sound when hit by a projectile

hitsound_volume

volume wanted for being hit

hud_list

This atom's HUD (med/sec, etc) images. Associative list.

hud_possible

HUD images that this atom can provide.

interaction_flags_atom

Intearaction flags

light

Our light source. Don't fuck with this directly unless you have a good reason!

light_color

Hexadecimal RGB string representing the colour of the light. White by default.

light_flags

Bitflags to determine lighting-related atom properties.

light_on

Boolean variable for toggleable lights. Has no effect without the proper light_system, light_range and light_power values.

light_power

Intensity of the light. The stronger, the less shadows you will see on the lit area.

light_range

Range of the light in tiles. Zero means no light.

light_sources

Any light sources that are "inside" of us, for example, if src here was a mob that's carrying a flashlight, that flashlight's light source would be part of this list.

light_system

Light systems, both shouldn't be active at the same time.

managed_overlays

overlays managed by update_overlays to prevent removing overlays that weren't added by the same proc

managed_vis_overlays

vis overlays managed by SSvis_overlays to automaticaly turn them like other overlays

material_flags

Bitfield for how the atom handles materials.

material_modifier

Modifier that raises/lowers the effect of the amount of a material, prevents small and easy to get items from being death machines.

no_connector_typecache

Typecache of atom types that this wall will NOT form connector overlays into when smoothing. Types should set this equal to a list; this list is, on init, used to create a typecache that is itself cached by SSicon_smooth.

orbit_target

Reference to atom being orbited

pass_flags_self

pass_flags that we are. If any of this matches a pass_flag on a moving thing, by default, we let them through.

rad_insulation

Radiation insulation types

reagents

Reagents holder

remove_overlays

a very temporary list of overlays to remove

ricochet_chance_mod

When a projectile tries to ricochet off this atom, the projectile ricochet chance is multiplied by this

ricochet_damage_mod

When a projectile ricochets off this atom, it deals the normal damage * this modifier to this atom

smoothing_flags

Icon-smoothing behavior.

smoothing_groups

What smoothing groups does this atom belongs to, to match canSmoothWith. If null, nobody can smooth with it.

smoothing_junction

What directions this is currently smoothing with. IMPORTANT: This uses the smoothing direction flags as defined in icon_smoothing.dm, instead of the BYOND flags.

targeted_by

Mobs that are currently do_after'ing this atom, to be cleared from on Destroy()

top_left_corner

Smoothing variable

top_right_corner

Smoothing variable

Proc Details

AllowDrop

Are you allowed to drop this atom

AltClickNoInteract

Use this instead of /mob/proc/AltClickOn where you only want turf content listing without additional atom alt-click interaction

Beam

This is what you use to start a beam. Example: origin.Beam(target, args). Store the return of this proc if you don't set maxdist or time, you need it to delete the beam.

Unless you're making a custom beam effect (see the beam_type argument), you won't actually have to mess with any other procs. Make sure you store the return of this Proc, you'll need it to kill the beam. Arguments: BeamTarget: Where you're beaming from. Where do you get origin? You didn't read the docs, fuck you. icon_state: What the beam's icon_state is. The datum effect isn't the ebeam object, it doesn't hold any icon and isn't type dependent. icon: What the beam's icon file is. Don't change this, man. All beam icons should be in beam.dmi anyways. maxdistance: how far the beam will go before stopping itself. Used mainly for two things: preventing lag if the beam may go in that direction and setting a range to abilities that use beams. beam_type: The type of your custom beam. This is for adding other wacky stuff for your beam only. Most likely, you won't (and shouldn't) change it.

CanAllowThrough

Returns true or false to allow the mover to move through src

CanPass

Whether the mover object can avoid being blocked by this atom, while arriving from (or leaving through) the border_dir.

CheckParts

Ensure a list of atoms/reagents exists inside this atom

Goes throught he list of passed in parts, if they're reagents, adds them to our reagent holder creating the reagent holder if it exists.

If the part is a moveable atom and the previous location of the item was a mob/living, it calls the inventory handler transferItemToLoc for that mob/living and transfers the part to this atom

Otherwise it simply forceMoves the atom into this atom

Click

Before anything else, defer these calls to a per-mobtype handler. This allows us to remove istype() spaghetti code, but requires the addition of other handler procs to simplify it.

Alternately, you could hardcode every mob's variation in a flat /mob/proc/ClickOn proc; however, that's a lot of code duplication and is hard to maintain.

Note that this proc can be overridden, and is in the case of screen objects.

ComponentInitialize

Put your AddComponent calls here

Destroy

Top level of the destroy chain for most atoms

Cleans up the following:

• Removes alternate apperances from huds that see them
• qdels the reagent holder from atoms if it exists
• clears the orbiters list
• clears overlays and priority overlays
• clears the light object

Entered

An atom has entered this atom's contents

Default behaviour is to send the COMSIG_ATOM_ENTERED

Exit

An atom is attempting to exit this atom's contents

Default behaviour is to send the COMSIG_ATOM_EXIT

Return value should be set to FALSE if the moving atom is unable to leave, otherwise leave value the result of the parent call

Exited

An atom has exited this atom's contents

Default behaviour is to send the COMSIG_ATOM_EXITED

GenerateTag

Generate a tag for this atom

HasProximity

Is this atom within 1 tile of another atom

Initialize

The primary method that objects are setup in SS13 with

we don't use New as we have better control over when this is called and we can choose to delay calls or hook other logic in and so forth

During roundstart map parsing, atoms are queued for intialization in the base atom/New(), After the map has loaded, then Initalize is called on all atoms one by one. NB: this is also true for loading map templates as well, so they don't Initalize until all objects in the map file are parsed and present in the world

If you're creating an object at any point after SSInit has run then this proc will be immediately be called from New.

mapload: This parameter is true if the atom being loaded is either being intialized during the Atom subsystem intialization, or if the atom is being loaded from the map template. If the item is being created at runtime any time after the Atom subsystem is intialized then it's false.

You must always call the parent of this proc, otherwise failures will occur as the item will not be seen as initalized (this can lead to all sorts of strange behaviour, like the item being completely unclickable)

You must not sleep in this proc, or any subprocs

Any parameters from new are passed through (excluding loc), naturally if you're loading from a map there are no other arguments

Must return an initialization hint or a runtime will occur.

Note: the following functions don't call the base for optimization and must copypasta handling:

• /turf/Initialize
• /turf/open/space/Initialize

IsObscured

Is the atom obscured by a PREVENT_CLICK_UNDER_1 object above it

LateInitialize

Sends a signal that the new atom src, has been created at loc Late Intialization, for code that should run after all atoms have run Intialization

To have your LateIntialize proc be called, your atoms Initalization proc must return the hint INITIALIZE_HINT_LATELOAD otherwise you will never be called.

useful for doing things like finding other machines on GLOB.machines because you can guarantee that all atoms will actually exist in the "WORLD" at this time and that all their Intialization code has been run

New

Called when an atom is created in byond (built in engine proc)

Not a lot happens here in SS13 code, as we offload most of the work to the Intialization proc, mostly we run the preloader if the preloader is being used and then call InitAtom of which the ultimate result is that the Intialize proc is called.

We also generate a tag here if the DF_USE_TAG flag is set on the atom

Topic

Passes Stat Browser Panel clicks to the game and calls client click on an atom

_Click

stupid workaround for byond not recognizing the /atom/Click typepath for the queued click callbacks

acid_act

Respond to acid being used on our atom

Default behaviour is to send COMSIG_ATOM_ACID_ACT and return

add_atom_colour

Adds an instance of colour_type to the atom's atom_colours list

add_mob_blood

to add blood from a mob onto something, and transfer their dna info

analyzer_act

Analyzer act

assume_air

Take air from the passed in gas mixture datum

attack_hand

Return TRUE to cancel other attack hand effects that respect it.

attack_hulk

This atom has been hit by a hulkified mob in hulk mode (user)

attackby

Called on an object being hit by an item

Arguments:

• obj/item/W - The item hitting this atom
• mob/user - The wielder of this item
• params - click params such as alt/shift etc

See: /obj/item/proc/melee_attack_chain

audible_message

Show a message to all mobs in earshot of this atom

Use for objects performing audible actions

vars:

• message is the message output to anyone who can hear.
• deaf_message (optional) is what deaf people will see.
• hearing_distance (optional) is the range, how many tiles away the message can be heard.

balloon_alert

Creates text that will float from the atom upwards to the viewer.

balloon_alert_to_viewers

Create balloon alerts (text that floats up) to everything within range. Will only display to people who can see.

bitmask_smooth

Basic smoothing proc. The atom checks for adjacent directions to smooth with and changes the icon_state based on that.

Returns the previous smoothing_junction state so the previous state can be compared with the new one after the proc ends, and see the changes, if any.

blob_act

React to a hit by a blob objecd

default behaviour is to send the COMSIG_ATOM_BLOB_ACT signal

bullet_act

React to a hit by a projectile object

Default behaviour is to send the COMSIG_ATOM_BULLET_ACT and then call on_hit on the projectile

@params P - projectile def_zone - zone hit piercing_hit - is this hit piercing or normal?

calculate_adjacencies

Scans all adjacent turfs to find targets to smooth with.

check_eye

Check if this atoms eye is still alive (probably)

component_storage_contents_dump_act

Implement the behaviour for when a user click drags another storage item to you

In this case we get as many of the tiems from the target items compoent storage and then put everything into ourselves (or our storage component)

TODO these should be purely component items that intercept the atom clicks higher in the call chain

connect_to_shuttle

Connect this atom to a shuttle

container_resist_act

Called when something resists while this atom is its loc

contents_explosion

Handle what happens when your contents are exploded by a bomb

contents_ui_distance

public

Check the distance for a living mob. Really only used for checks outside the context of a mob. Otherwise, use shared_living_ui_distance().

required src_object The object which owns the UI. required user mob The mob who opened/is using the UI.

return UI_state The state of the UI.

create_reagents

Convenience proc to create a reagents holder for an atom

Arguments:

• max_vol - maximum volume of holder
• flags - flags to pass to the holder

crowbar_act

Crowbar act

drop_location

Where atoms should drop if taken from this atom

emag_act

Respond to an emag being used on our atom

Default behaviour is to send COMSIG_ATOM_EMAG_ACT and return

emp_act

React to an EMP of the given severity

Default behaviour is to send the COMSIG_ATOM_EMP_ACT signal

If the signal does not return protection, and there are attached wires then we call emp_pulse on the wires

We then return the protection value

ex_act

React to being hit by an explosion

Default behaviour is to call contents_explosion and send the COMSIG_ATOM_EX_ACT signal

examine

Called when a mob examines (shift click or verb) this atom

Default behaviour is to get the name and icon of the object and it's reagents where the [TRANSPARENT] flag is set on the reagents holder

Produces a signal COMSIG_PARENT_EXAMINE

examine_more

Called when a mob examines (shift click or verb) this atom twice (or more) within EXAMINE_MORE_TIME (default 1.5 seconds)

This is where you can put extra information on something that may be superfluous or not important in critical gameplay moments, while allowing people to manually double-examine to take a closer look

Produces a signal COMSIG_PARENT_EXAMINE_MORE

expose_reagents

• Handles exposing this atom to a list of reagents.

• Sends COMSIG_ATOM_EXPOSE_REAGENTS

• Calls expose_atom() for every reagent in the reagent list.

• Arguments:

• • reagents: The list of reagents the atom is being exposed to.
• • source: The reagent holder the reagents are being sourced from.
• • method: How the atom is being exposed to the reagents.
• • volume_modifier: Volume multiplier.
• • show_message: Whether to display anything to mobs when they are exposed.

find_type_in_direction

Scans direction to find targets to smooth with.

get_dumping_location

Get the best place to dump the items contained in the source storage item?

get_examine_name

Get the name of this object for examine

You can override what is returned from this proc by registering to listen for the COMSIG_ATOM_GET_EXAMINE_NAME signal

get_examine_string

Generate the full examine string of this atom (including icon for goonchat)

get_filter_index

Returns the indice in filters of the given filter name. If it is not found, returns null.

get_remote_view_fullscreens

the vision impairment to give to the mob whose perspective is set to that atom

(e.g. an unfocused camera giving you an impaired vision when looking through it)

get_save_vars

This has been made semi-modular so you should be able to use these functions elsewhere in code if you ever need to get a file in the .dmm format

get_screentip_name

Returns the atom name that should be used on screentip

handle_atom_del

This proc is called when an atom in our contents has it's Destroy called

Default behaviour is to simply send COMSIG_ATOM_CONTENTS_DEL

handle_fall

Used for making a sound when a mob involuntarily falls into the ground.

handle_slip

Handle the atom being slipped over

has_gravity

Returns true if this atom has gravity for the passed in turf

Sends signals COMSIG_ATOM_HAS_GRAVITY and COMSIG_TURF_HAS_GRAVITY, both can force gravity with the forced gravity var

Gravity situations:

• No gravity if you're not in a turf
• No gravity if this atom is in is a space turf
• Gravity if the area it's in always has gravity
• Gravity if there's a gravity generator on the z level
• Gravity if there is a ship gravity generator in a ship
• Gravity if the Z level has an SSMappingTrait for ZTRAIT_GRAVITY
• otherwise no gravity

hitby

React to being hit by a thrown object

Default behaviour is to call hitby_react on ourselves after 2 seconds if we are dense and under normal gravity.

Im not sure why this the case, maybe to prevent lots of hitby's if the thrown object is deleted shortly after hitting something (during explosions or other massive events that throw lots of items around - singularity being a notable example)

hitby_react

We have have actually hit the passed in atom

Default behaviour is to move back from the item that hit us

in_contents_of

Return true if we're inside the passed in atom

is_drainable

Is this atom drainable of reagents

is_drawable

Can we draw from this atom with an injectable atom

is_injectable

Is this atom injectable into other atoms

is_open_container

Convenience proc to see if a container is open for chemistry handling

is_refillable

Can this atoms reagents be refilled

isinspace

Is this atom in space

join_player_here

Called whenever a player is spawned on the same turf as this atom.

log_message

Generic logging helper

log_talk

Helper for logging chat messages or other logs with arbitrary inputs (e.g. announcements)

mat_update_desc

This proc is called when a material updates an object's description

mech_melee_attack

Handle melee attack by a mech

multitool_act

Multitool act

multitool_check_buffer

Check if the multitool has an item in it's data buffer

narsie_act

Respond to narsie eating our atom

Default behaviour is to send COMSIG_ATOM_NARSIE_ACT and return

onAwayMission

Is the atom in an away mission

Must be in the away mission z-level to return TRUE

Also used in gamemode code for win conditions

onCentCom

Is this atom currently located on centcom

Specifically, is it on the z level and within the centcom areas

You can also be in a shuttleshuttle during endgame transit

Used in gamemode to identify mobs who have escaped and for some other areas of the code who don't want atoms where they shouldn't be

onSyndieBase

Is the atom in any of the centcom syndicate areas

Either in the syndie base on centcom, or any of their shuttles

Also used in gamemode code for win conditions

on_log

Called when the atom log's in or out

Default behaviour is to call on_log on the location this atom is in

on_mouse_enter

Fired whenever this atom is the most recent to be hovered over in the tick. Preferred over MouseEntered if you do not need information such as the position of the mouse. Especially because this is deferred over a tick, do not trust that client is not null.

prepare_huds

Prepare the huds for this atom

Goes through hud_possible list and adds the images to the hud_list variable (if not already cached)

rad_act

Respond to a radioactive wave hitting this atom

Default behaviour is to send COMSIG_ATOM_RAD_ACT and return

rcd_act

Respond to an RCD acting on our item

Default behaviour is to send COMSIG_ATOM_RCD_ACT and return FALSE

rcd_vals

Return the values you get when an RCD eats you?

relaymove

An atom we are buckled or is contained within us has tried to move

Default behaviour is to send a warning that the user can't move while buckled as long as the buckle_message_cooldown has expired (50 ticks)

remove_air

Remove air from this atom

remove_atom_colour

Removes an instance of colour_type from the atom's atom_colours list

return_air

Return the current air environment in this atom

return_analyzable_air

Return the air if we can analyze it

return_temperature

Return atom temperature

runechat_prefs_check

Returns the client runechat visible messages preference according to the message type.

say_emphasis

Scans the input sentence for speech emphasis modifiers, notably |italics|, +bold+, and underline -mothblocks

screwdriver_act

Screwdriver act

setDir

Hook for running code when a dir change occurs

Not recommended to use, listen for the COMSIG_ATOM_DIR_CHANGE signal instead (sent by this proc)

set_base_pixel_x

Setter for the "base_pixel_x" var to append behavior related to it's changing

set_base_pixel_y

Setter for the "base_pixel_y" var to append behavior related to it's changing

set_custom_materials

Sets the custom materials for an item.

set_opacity

Updates the atom's opacity value.

This exists to act as a hook for associated behavior. It notifies (potentially) affected light sources so they can update (if needed).

set_smoothed_icon_state

Changes the icon state based on the new junction bitmask. Returns the old junction value.

shuttleRotate

Base proc

singularity_act

Respond to the singularity eating this atom

singularity_pull

Respond to the singularity pulling on us

Default behaviour is to send COMSIG_ATOM_SING_PULL and return

storage_contents_dump_act

Implement the behaviour for when a user click drags a storage object to your atom

This behaviour is usually to mass transfer, but this is no longer a used proc as it just calls the underyling /datum/component/storage dump act if a component exists

TODO these should be purely component items that intercept the atom clicks higher in the call chain

tool_act

Tool behavior procedure. Redirects to tool-specific procs by default.

You can override it to catch all tool interactions, for use in complex deconstruction procs.

Must return parent proc ..() in the end if overridden

transfer_mob_blood_dna

to add a mob's dna info into an object's blood_dna list.

update_appearance

Updates the appearence of the icon

Mostly delegates to update_name, update_desc, and update_icon

Arguments:

• updates: A set of bitflags dictating what should be updated. Defaults to [ALL]

update_atom_colour

Resets the atom's color to null, and then sets it to the highest priority colour available

update_desc

Updates the description of the atom

update_icon

Updates the icon of the atom

update_icon_state

Updates the icon state of the atom

update_name

Updates the name of the atom

update_overlays

Updates the overlays of the atom

update_remote_sight

the sight changes to give to the mob whose perspective is set to that atom

(e.g. A mob with nightvision loses its nightvision while looking through a normal camera)

virtual_z

Used to get the virtual z-level. Will give unique values to each shuttle while it is in a transit level. Note: If the user teleports to another virtual z on the same z-level they will need to have reset_virtual_z called. (Teleportations etc.) Virtual Z is optimized lookup of the virtual level for comparisons, but it doesn't pass the reference

visible_message

Generate a visible message from this atom

Show a message to all player mobs who sees this atom

Show a message to the src mob (if the src is a mob)

Use for atoms performing visible actions

message is output to anyone who can see, e.g. "The [src] does something!"

Vars:

• self_message (optional) is what the src mob sees e.g. "You do something!"
• blind_message (optional) is what blind people will hear e.g. "You hear something!"
• vision_distance (optional) define how many tiles away the message can be seen.
• ignored_mob (optional) doesn't show any message to a given mob if TRUE.

vv_get_dropdown

Return the markup to for the dropdown list for the VV panel for this atom

Override in subtypes to add custom VV handling in the VV panel

wash

Wash this atom

This will clean it off any temporary stuff like blood. Override this in your item to add custom cleaning behavior. Returns true if any washing was necessary and thus performed Arguments:

• clean_types: any of the CLEAN_ constants

welder_act

Welder act

wirecutter_act

Wirecutter act

wrench_act

Wrench act

zap_act

Respond to a electric bolt action on our item

Default behaviour is to return, we define here to allow for cleaner code later on