Internal documentation dump

This is where I dump all the internal documentation of 2.2 features that I can find, so y'all can put it on the wiki. Be warned that some of the information may be outdated, so it's a good idea to double-check stuff first.

Damage types

This is an additional argument to P_DamageMobj, P_KillMobj, and functions for the hooks ShouldDamage, MobjDamage, MobjDeath and HurtMsg. As you can guess, they tell the game what type of damage was dealt to the target. However, nearly all of them do something special only for players.

Here is the full list of damage type constants currently in master branch (0 is considered to be the default "type"):

DMG_WATER - Water damage (old THZ harmful goop)
DMG_FIRE - Fire damage (MF_FIRE, lava)
DMG_ELECTRIC - Electric damage (THZ electric floors)
DMG_SPIKE - Spike damage (Spike Things, Spikes sector type)
DMG_NUKE - Armageddon shield explosion
DMG_INSTAKILL Generic instant kill (this marks the start of the "instant kill" types)
DMG_DROWNED - Died by drowning
DMG_SPACEDROWN - Died in space countdown sector
DMG_DEATHPIT - Died in death pit
DMG_CRUSHED - Died by crusher/solid objects landing on top of you
DMG_SPECTATOR - This allows you to kill spectators
DMG_DEATHMASK - A special mask/flag constant that allows you to check if a damage type is "instant kill" or not (e.g. damagetype & DMG_DEATHMASK)

New Lua hooks

"ShieldSpawn" - A hook called when a shield orb spawning function (like P_SpawnShieldOrb, or any of the monitor spawning functions) is called. Takes player as argument. If returning true, do not spawn existing orb.
"ShieldSpecial" - A hook called when pressing spin in midair and you have any shield in SH_NOSTACK (ie, not the fire flower). Takes player as argument. If returning true, do not perform existing shield actions.
"MobjMoveBlocked" - A hook that calls functions when your X/Y movement is blocked. It doesn't matter what stopped you, though you have no way to tell anyway. See this Gitlab MR for info: http://git.magicalgirl.moe/STJr/SRB2...ge_requests/67
"MapThingSpawn" - A hook that calls functions when a certain object type is spawned via a Map Thing on level load. See this GitLab MR for info: http://git.magicalgirl.moe/STJr/SRB2...ge_requests/83

Getting sprite patches for the HUD:

Begone with ye terrible hacks involving getting the sprite lumps by exact name, I have made a more sophisticated method of getting sprite patches! They come in the form of two video library functions accessible only through hud.add functions, named v.getSpritePatch (for normal sprites) and v.getSprite2Patch (for character skin sprites).

See this GitLab MR for info: http://git.magicalgirl.moe/STJr/SRB2...e_requests/105

Miscellaneous changes you may want to know about:

Also included in the "Lua additions" branch (linked in "Blockmap search" section) is the function P_PointOnLineSide(x, y, line), which basically returns which side of a line the x,y position is on (0 = front, 1 = back). You can even supply a custom line like with P_ClosestPointOnLine!
userdataType(variable) now exists to print the userdata type of whatever you supply as a string, e.g. "player_t" or "mobj_t". Was included with this MR: http://git.magicalgirl.moe/STJr/SRB2...ge_requests/67

Plane displacement

Linedef types 66-68 are the plane displacement specials; 66 = move floor only, 67 = move ceiling only, 68 = both

Front sector = control sector
Tag = tag of target sectors to be moved whenever the control sector floor moves
Linedef length = movement factor relative to control sector movement, 256 = 1:1 with control sector. 128 is half as much, 512 is twice as much, etc.

Whenever the control sector floor moves (not ceiling, never ceiling), the selected planes of the tagged sectors all move (mind, they have a tic delay due to how it all works, it's not perfect really).

Turn on Not Climbable on any of the plane displacement linedef types to enable inverse plane displacement for any sectors tagged by them. This causes moving the control sector to move all tagged sector planes in the reverse direction.

FOF wall slope skewing

FOF walls now can optionally skew with respect to slopes (software mode only currently):

Upper Unpegged on the CONTROL linedef enables wall skewing
Lower Unpegged on the IN-LEVEL linedefs ^1 determine which slope to skew with respect to (off = top slope, on = bottom slope)
If Transfer Line is used however, Lower Unpegged on the control sector's linedefs does the above's job instead

^1 (this is because they already control pegging of individual FOF walls as it is, so this is for convenience and my sanity that they also deal with skewing)

TEXTURES additions

Some new features and fixes for textures and the TEXTURES lump:

Flipping of individual patches used by textures is now supported, both horizontally and vertically. The formatting for doing so in TEXTURES should match that of ZDoom's:

WallTexture EXAMPLE, 128, 128
{
	Patch TEST, 0, 0
	Patch TEST, 64, 0
	{
		FlipX
	}
	Patch TEST, 0, 64
	{
		FlipY
	}
	Patch TEST, 64, 64
	{
		FlipX
		FlipY
	}
}

(in other words you need { and } below the Patch you want to flip, containing FlipX if you want horizontal flipping or FlipY if you want vertical flipping... or both, if you want both!)

Negative patch y-offsets should now work properly for multi-patch textures or single-patch textures with no holes.

Crumble FOF

EV_StartCrumble for lua, format: EV_StartCrumble(controlsec, rover, [floating?, [player, [origalpha, [crumblereturn?]]]])
controlsec is the FOF's control sector
rover is the FOF itself
(optional) floating? does the FOF float on water after crumbling? Defaults to false (NOTE: probably should be set to rover.flags & FF_FLOATBOB for best results currently, kind of weird otherwise)
(optional) player is the player that caused the FOF to fall; needed for some effects such as who to award points to if you killed someone =3 Defaults to nil
(optional) origalpha is the FOF's original alpha before crumbling (the thinker for respawning + floating crumbling FOFs tinkers with the alpha for some reason). Defaults to rover.alpha
(optional) crumblereturn? will the FOF respawn afterwards? Defaults to false (NOTE: probably should be set to not (rover.flags & FF_NORETURN) for best results currently, kind of weird otherwise)
the return value of EV_StartCrumble means something I forget offhand now ...it's either true or false though, mind

Damage control + Match rebalancing

Changes from damage-control:

player->health (formerly the "HUD copy" of player->mo->health) is now player->rings, and is also now the player's actual ring count.
player->mo->health (formerly rings + 1) is now always 1 when alive, regardless of ring count; if player with rings is damaged, this is untouched.
P_RingDamage now includes ring spilling code.
P_ShieldDamage now has a damagetype argument, allowing me to remove the last MT_NULL hack left in from the pre-damagetype days that I forgot about.
The old "switch-to-seestate" enemy damaging behavior in P_DamageMobj has been removed. This was a Doom left-over and doesn't really affect SRB2's enemies anyway - see, Doom enemies had a random chance of using seestate or painstate, SRB2 enemies always use painstate.
Other minor efforts to reorganise damaging code and have it make more sense, but otherwise nothing that should affect gameplay in general.

Changes from match-rebalancing:

New weapon/ammo dropping behavior: if you have the weapon panel + ammo, you drop the panel (but not the ammo); if you don't, you just drop the ammo.
New Match ammo consumption: Weapon rings can now be fired with no rings at double the ammo cost.
New emerald behaviour: collecting all 7 emeralds no longer turns you super (read: Match super is dead now) but instead steal points from enemies and gives you and teammates invincibility + sneakers
Tails ringslinger buff: Any character with CA_FLY will now throw rings 1.5x as fast.

New tutorial features

Monitor Pop - Run Linedef Exec

Set MTF_EXTRA on the monitor thing
Set thing Angle to Tag + 16384

Linedef Exec Effect 457: Track Object Angle

Track mobj/player's angle to a focal Thing. If the player faces away from the Thing by N degrees, it executes a linedef executor.

Place focal Thing 758 MT_ANGLEMAN in a target sector
Place line effect with Tag set to the target sector, so it can search for the focal Thing.

Front X Offset - Angle tolerance, i.e., mobj needs to face more than this many degrees away from tracer to fail
Front Y Offset - Tic tolerance, i.e., how many tics to allow lookaway before executing linedef?
Back X Offset - Tag to execute upon lookaway
ML_EFFECT2 - Continue checking after first lookaway (default: disable checking after the first lookaway)
Tag - Target sector to look for Thing 758 MT_ANGLEMAN

Linedef Exec Effect 458: Stop Tracking Object Angle

Stops all checking behavior set by Line Exec 457.

Linedef Exec Effect 459: Control Text Prompt

Front X Offset: Prompt number
Front Y Offset: Page number, 0 means to start from beginning
Block Monsters: Close the current prompt
Effect1: Trigger Linedef Exec specified by Back X Offset when prompt is closed
NoClimb: Display prompt for all players (default: only triggering player)
Effect2: Do not block controls (default: block controls)
Effect3: Don't freeze player's realtime level timer (default: freeze the timer)
Transfer Line: Search for prompt by named tag; ignore X/Y offsets
- Front Texture: Tag name to search for, case-insensitive.
  - If tutorialmode, the following control modes will be appended to this name automatically: FPS, Platform, Custom

SOC Spec

Prompt

NumPages - Number of pages specified. This must be set for the game to recognize the pages.

Sample SOC

# Area 1 pre-text
PROMPT 1
NumPages 3
PAGE 1
Name = Scratch
Icon = SCRATCH
IconAlign = Left
Lines = 4
PageText = Welcome to the SRB2 Tutorial!\ba To access the menu,\b4 hit the \82escape key\80.\baTo continue,\b4 press \82\c(Jump)\80.
        #
PAGE 2
Name = Grounder
Icon = GROUNDER
IconAlign = Right
Lines = 4
PageText = To move around, press the movement keys:\ba \82\c(Move)\80
        #
PAGE 3
MetaPage = 1
PageText = Use the movement keys to reach the exit.
        #

# Area 1 HUD prompt
PROMPT 2
NumPages 3
PAGE 1
Name = Movement
Icon = STARORB
Lines = 3
TextSpeed = TICRATE/5
TimeToNext = TICRATE*3
PageText = Use \82\c(Move)\80 to move.
        #
PAGE 2
MetaPage = 1
TimeToNext = TICRATE*4
PageText = Automatic braking is on by default,\b4 which causes you to slow down quickly
        #
PAGE 3
MetaPage = 1
NextPage = 1
TimeToNext = TICRATE*3
PageText = when you release the controls.
        #

Caveats

PageText hash string terminating is @$#&^$%^& broken because of dehacked.c myhashfgets, which is used by cutscenes (SceneText). The function originally returned a string that included the terminating # char plus one extra char after that. I fixed this issue; the fix shouldn't break cutscenes. However, malformed files (like if you forget to terminate with #) still cause errors and unparsed lines, so check log.txt and make sure every line is being processed.
- Make sure there is no whitespace after terminating # char
- Make sure there is no whitespace (leading tabs) in the line after the terminating #

GitLab