Surgery Code Refactor

From op_stage to surgeryHolder

• Surgery Code Refactor
  • Foreword
  • Goals & Non-Goals
    • Goals
    • Non-goals
  • Current Implementation
    • Impact of current design on code
    • The Underlying Issue
  • Proposed Implementation
    • Diagram
    • Component Parts
    • Supplemental Parts
    • State Storage Example
    • Other Additions
    • Benefits
    • Challenges

Foreword

This is a difficult problem, and the currently implemented solution most importanly works very consistently; it's already worked through most potential corner-cases and potential issues. I am coming to this code with a different objective and perspective, many years on from the original constraints that this design fulfilled.

Thank you for your consideration.

Goals & Non-Goals

Goals

1. Make it easier to figure out current/next surgery states
2. Reduce duplication within surgery code
3. Provide greater flexibility for creating/modifying surgery steps

Non-goals

1. Disrupt the current player actions/order for surgery

Current Implementation

Surgery status is handled via an integer variable stored on an object, usually the organ, and which "stage" the surgery is in is represented via integers. These integers live on different objects:

• Every /obj/item/organ (i.e. head, chest, internal organs)
  • op_stage - keeps track of the current OPeration STAGE
  • organ_holder_required_op_stage - value to check against op_stage when attaching
• Every /obj/item/parts (i.e. limbs) has the remove_stage variable
• Every /obj/item/organ/head has the scalp_op_stage variable
• Every /mob/living has the butt_op_stage variable

These integers are then gently nudged by large procs custom built for each surgery type. Individual items must specifically call the related surgery proc in order to attempt surgery.

Impact of current design on code

The more surgery steps done with the tool, the greater the complexity of individual procs:

Surgery Proc Name	Lines in File	Number of ifs
scalpel_surgery	690	81
saw_surgery	361	46
suture_surgery	165	29
cautery_surgery	150	19
spoon_surgery	105	16
snip_surgery	271	32
crowbar_surgery	54	8
wrench_surgery	34	8

In addition, this complexity spills out into other code; get_desc.dm can be impenetrable without knowing op_stages. Within surgery_procs itself, there are duplicated sections of code that resist condensing into helper procs because they are, in essence, data about the surgery step. This style of design makes the data encoded within difficult to use in other contexts without writing bespoke interpretations for the various organs and op_stage values.

To quote from the code at writing:

Understanding Op Stages
Step 1 - dont
Step 2 - uhg, fine

The Underlying Issue

This is a difficult problem.

Surgery itself has state, and is also the interface between a surgeon and several other state systems at once:

• the /datum/human_limbs system for limbs
• the /datum/organHolder system for internal organs
• changes to the system are called from various /obj/item/ attacks

It also interacts more directly with some other play systems:

• Trait checking (clumsy, training_medical)
• bioHolder.mutantrace (tails, skeletons) on some surgery types

Proposed Implementation

Represent the state of surgery as a set of node graphs, with a state machine-like traversal proc.

This works alongside the existing limb and organHolder systems; it is not a replacement.

Diagram

This shows all node graphs, joined together for ease of viewing; not designed to work with the Simulate option.
https://stately.ai/registry/editor/3668c891-176d-4275-9b7c-adca95c720fc?machineId=a9531a72-9fd9-4a9f-a011-c4468208e88b

Component Parts

• A node in the graph, node
  • The transitions map, whose keys are other node datums and values are a map:
    • conditions - a list of condition
    • effects - a list of effect
  • Static data about the surgery state (e.g. descriptions for examine)
  • These are not mutated. They can be reused across all mobs.
• A condition that must be met, condition
  • Calls a check proc that returns bool TRUE/FALSE
  • Can contain variable data
  • Can be any check on the surgeon, patient, or tool; commonly:
    • /datum/surgeryHolder/condition/has/* has a part in place?
    • /datum/surgeryHolder/condition/tool/* surgeon's tool?
    • /datum/surgeryHolder/condition/intent/* surgeon's intent?
    • /datum/surgeryHolder/condition/hand/* surgeon using specific hand?
• A side-effect of changing nodes, effect
  • Calls a do_effect proc
  • Can contain variable data e.g. min-max for damage rolls
  • Can do anything to the surgeon, patient, or tool; commonly:
    • /datum/surgeryHolder/effect/damage/* surgery damage
    • /datum/surgeryHolder/effect/bleed Bleed damage/animation
    • /datum/surgeryHolder/condition/attach/* Part (de-)attachment
• A proc for which surgery to try, get_surgery_transition
  • Runs the check for every condition
  • If all checks run, return the next node & effects to take on success
• The traversal proc, attempt_surgery
  • Rolls the actual surgery success attempt
  • On success
    • Applies side effects
    • Changes relevant surgeryHolder state

Supplemental Parts

• Surgeon zone_sel switch to determine which graph(s) to check
  • Reduces complexity of node graphs considerably
• Re-use/adapt some existing surgery procs
  • surgeryCheck - adaptable
  • calc_screw_up_prob - as-is

State Storage Example

From some lightweight testing, I think this is the minimum collection of graphs to keep track of.

This is an example of what we'd commonly see on a new /mob/living/carbon/human, having all their parts together.

• /obj/item/organ/head
  • var/list/surgeryHolders
    • "neck" = /datum/surgeryHolder/node/neck/attached
    • "l_eye" = /datum/surgeryHolder/node/l_eye/attached
    • "r_eye" = /datum/surgeryHolder/node/r_eye/attached
    • "brain" = /datum/surgeryHolder/node/brain/attached
• /obj/item/organ/chest
  • var/surgeryHolder
    • /datum/surgeryHolder/node/chest/neutral
• /obj/item/limb
  • var/surgeryHolder
    • /datum/surgeryHolder/node/limb/attached

Other Additions

• New item flag: surgery_flags & helper issurgerytool defines
  • assigning items as surgery tools is super easy
  • minimize special handling for tools with multiple potential uses (welder, omnitool)

Benefits

• Much smaller size per-function
  • Easy to add individual condtions and effects to surgery
• Data is structured so we can programatically find next steps
  • User interfaces can rely on game data for surgery steps
• Possible to include secret surgeries
• Potential for validating the node graph works correctly in test

Challenges

• Debugging requires understanding node traversal
• Replacing all op_stage checks is a lot of work
• Unknown size of impact on secret content