Skip to content

Fix method passing for On Depart hook - #7911

Open
wookieejedi wants to merge 2 commits into
scp-fs2open:masterfrom
wookieejedi:on-depart-method-cleanup
Open

wookieejedi wants to merge 2 commits into
scp-fs2open:masterfrom
wookieejedi:on-depart-method-cleanup

Conversation

@wookieejedi

Copy link
Copy Markdown
Member

ship_actually_depart_helper throws away the departure method — it only forwards a bool:

// ship.cpp:8940
dfi.parameter_variables.bool_value = (method == SHIP_VANISHED ? true:false); // ship.cpp:8930
ship_cleanup(objp->instance, infop->parameter_variables.bool_value ? SHIP_VANISHED : SHIP_DEPARTED);

So SHIP_DEPARTED_WARP and SHIP_DEPARTED_BAY are flattened to SHIP_DEPARTED before ship_cleanup ever sees them. Consequences: OnShipDepart’s Method param can only ever be SHIP_DEPARTED, SHIP_VANISHED, or SHIP_DEPARTED_REDALERT, even though global_hooks.cpp:356 documents SHIP_DEPARTED_WARP and SHIP_DEPARTED_BAY as possible values — those two are unreachable. Ship_registry[].cleanup_mode loses the distinction too. The fix is to carry method through dock_function_info instead of the bool.

ship_actually_depart_helper throws away the departure method — it only forwards a bool:

// ship.cpp:8940
dfi.parameter_variables.bool_value = (method == SHIP_VANISHED ? true:false);
// ship.cpp:8930
ship_cleanup(objp->instance, infop->parameter_variables.bool_value ? SHIP_VANISHED : SHIP_DEPARTED);

So SHIP_DEPARTED_WARP and SHIP_DEPARTED_BAY are flattened to SHIP_DEPARTED before ship_cleanup ever sees them. Consequences: OnShipDepart’s Method param can only ever be SHIP_DEPARTED, SHIP_VANISHED, or SHIP_DEPARTED_REDALERT, even though global_hooks.cpp:356 documents SHIP_DEPARTED_WARP and SHIP_DEPARTED_BAY as possible values — those two are unreachable. Ship_registry[].cleanup_mode loses the distinction too. The fix is to carry method through dock_function_info instead of the bool.
@wookieejedi wookieejedi added cleanup A modification or rewrite of code to make it more understandable or easier to maintain. scripting A feature or issue related to LUA scripting labels Oct 19, 2026

@dustinspace217 dustinspace217 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good. Every caller passes a single method that ship_cleanup already handles, so the only visible change is the hook's Method string. A few small things: the bool_value assignment in ship_actually_depart is dead now and can go. Since warp and bay now report SHIP_DEPARTED_WARP and SHIP_DEPARTED_BAY, nothing emits plain SHIP_DEPARTED anymore. No script in my installed mods reads Method (loose files and packed .vp archives), but a line in the description would help, and the doc could mark 'SHIP_DEPARTED' as kept for compatibility, no longer emitted. Optional: its type there says "ship" where it's a string. A short Testing note would also help.

ship_actually_depart_helper now reads the method from int_value, so the bool_value assignment is unused. The hook's Method parameter is a string, and warp and bay departures now report their own method instead of SHIP_DEPARTED.
@dustinspace217

Copy link
Copy Markdown
Contributor

I pushed one small commit with the cleanup from my review: the unused bool_value assignment is gone, and the On Ship
Depart doc now lists the methods that are actually sent. Method is a string, and warp and bay departures no longer
send SHIP_DEPARTED. Built on Linux, Debug, no warnings.

@Goober5000 Goober5000 left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two inline comments. Plus for the OnShipDepart definition itself, in global_hooks.cpp, the "Method" parameter is described as "ship" when it should be "string".

Comment thread code/ship/ship.cpp Resolved
Comment thread code/ship/ship.cpp
Comment on lines +8942 to +8944
Assertion(method & (SHIP_DEPARTED | SHIP_VANISHED | SHIP_DEPARTED_REDALERT),
"Invalid departure method '%i' passed to ship_actually_depart for ship %s!", method, Ships[shipnum].ship_name);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This assertion isn't needed because nothing in this function depends on it, and ship_cleanup already asserts

{"Ship", "ship", "The ship departing the mission"},
{"JumpNode", "string", "The name of the jump node the ship was in when it departed. Can be nil."},
{"Method", "ship", "The name of the method the ship used to depart. One of: 'SHIP_DEPARTED', 'SHIP_DEPARTED_WARP', 'SHIP_DEPARTED_BAY', 'SHIP_VANISHED', 'SHIP_DEPARTED_REDALERT'."},
{"Method", "string", "The name of the method the ship used to depart. One of: 'SHIP_DEPARTED_WARP', 'SHIP_DEPARTED_BAY', 'SHIP_VANISHED', 'SHIP_DEPARTED_REDALERT'. Older builds sent 'SHIP_DEPARTED' for warp and bay departures; it is no longer sent."},

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SHIP_DEPARTED should not be deleted from the list. It was a possible value before, and it may be a possible value in the future. Script authors should still be aware of the value.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cleanup A modification or rewrite of code to make it more understandable or easier to maintain. scripting A feature or issue related to LUA scripting

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants