User:Kaysakado/hookorderdraft

In general, how would this best be formatted? Pseudo code, actual code, plain prose descriptions? One big table, subheadings, collapsible sections? I'm pretty lost on this so definitely looking for suggestions here

This is intended to focus on Lua hooks - how much of the surrounding logic is useful or necessary to have? For example, is it enough for a scripter to just know that `"MobjCollide"` is called during `PIT_CheckThing` and leave them to consult the source if they need more specifics, or should the most relevant hardcoded portions of `PIT_CheckThing` be documented as well?

In a perfect world, there would be one clean order that everything goes through, but this is not the case in a complex engine such as SRB2's. For functions like `P_CheckPosition`, which can be called in multiple different scenarios, what would be the best way to document this:

• Make a section for them outside of the main loop as done below?
• Document them in a "primary" position in the main loop, while making a note of where else they might be called?
• Keep every function in its own section - any time we go deeper in scope, link to a new section?

GENERAL ORDER

HOOK: "PreThinkFrame"
for each player:

HOOK: "PlayerThink"

for each mobj:

HOOK: "MobjThinker"

P_XYMovement

for each object collided with during PIT_CheckThing:

HOOK: "MobjCollide"

HOOK: "MobjMoveCollide"

for each line collided with during PIT_CheckLine:

HOOK: "MobjLineCollide"

HOOK: "MobjMoveBlocked" (only if move blocked)

P_ZMovement (only called when necessary)

PIT_CheckThing is called again (several times?) here. PIT_CheckLine is as well, but won't pick up new lines (?).

HOOK: "ThinkFrame"
HOOK: "PostThinkFrame"

P_Ticker()
	"PreThinkFrame"
	for each player in the game with a valid mobj
		P_PlayerThink()
			"PlayerThink" always the last thing called but can trigger early and return in certain cases
	P_RunThinkers()
		THINK_POLYOBJ
		THINK_MAIN
		THINK_MOBJ i.e. P_MobjThinker()
			return if  MF_NOTHINK or disabled MF_BOSS
			remove dead targets/tracers
			remove MFE_PUSHED/MFE_SPRUNG
			remove tmfloorthing and tmhitthing
			check for (2, 8) linedef executor
			run scale thinker
			hardcoded MT_GHOST/MT_THOK fades
			if MF_SCENERY
				P_MobjSceneryThink()
					"MobjThinker"
					return if true
					other stuff
				return
			if !mobj->player
				"MobjThinker"
				return if true or mobj was removed
			elseif !mobj->player->spectator
				"MobjThinker"
				return only if mobj was removed
			other specialized thinkers....
			if mobj has x or y momentum, or is skullflying
				P_XYMovement()
					stuff....
					P_Trymove()
						stuff.
						P_CheckPosition() see below
						stuff.
					if move failed and mobj wasn't removed or sprung
						(blocked)
						player blocked thinker
						"MobjMoveBlocked"
						other stuff
					other stuff
					P_XYFriction()
				return if mobj was removed
			if we should do zmovement (elaborate)
				if not P_ZMovement()
					return (mobj was removed... check if other cases where zmovement returns false)
				P_CheckPosition() see below
				return if mobj was removed
			else
				set pmomz to 0
				remove MFE_JUSTHITFLOOR
			end
			more stuff goes here...
		THINK_DYNSLOPE
		THINK_PRECIP
	for each player in the game with a valid mobj
		P_PlayerAfterThink()
			handles some carry and camera stuff idk
	"ThinkFrame"
	other stuff mostly gametype logic etc
	"PostThinkFrame"

P_CheckPosition()
	stuff goes here
	PIT_CheckThing
		stuff
		"MobjCollide"
		"MobjMoveCollide"
		stuff
	PIT_CheckLine
		stuff
		"MobjLineCollide"
		stuff
	more stuff