FreeSpace Releases > Scripting Releases

Movements-SEXPs, capship useful (v2.5)

(1/7) > >>

Release of Custom-Movements-SEXPs
Custom sexps and functions for FSO that allow for much easier ship movements and rotations.
v2.5 (November 18, 2023)

TLDR: Release of custom sexps which can make cap ship (or any ship) movements much easier and more natural looking.

Do you ever get frustrated when trying and get large ship movements to look good? I've found this be especially tricky if you want the ships to act dynamically, if you want big ships to rotate in a way that looks natural, or if you want many big ships to follow a leader ship and stay in a relative formation. Dynamic waypoints provide an invaluable tool, yet ships will stop following a waypoint path once the path is complete or immediately turn around to start the path again. I wanted a single sexp that told a ship to track a waypoint or ship, thus the ship would travel to the waypoint and then move again if the waypoint moved.

It can be similarly tricky to get large ships to rotate to a certain orientation. The rotation maneuver sexp is useful but you aren't guaranteed that the ship will stop rotating when it reaches the desired orientation. Again, I wanted a single sexp that I could use once that would move a ship to a specified orientation with a natural looking movement.

Also, recent updates have focused on making scripted movements look natural and precise. For example, values in the sexp can be set to have ships precisely stop on waypoints, then use the natural AI methods to rotate. There’s also the addition of a 'semi-smart' waypoint order, where AI ships following waypoints will check for obstacles in their path, then stop if they are on course to hit something. Once the obstacle leaves then the path will resume.

To achieve these goals, I developed a suite of custom lua sexps, and hopefully you might find something useful to your own missions!

In this release I have included sexps to rotate ships to a specific orientation, have a waypoint track a ship, a ship track a waypoint, and a ship track another ship. Fun things you can do with these sexps is to have entire fleet all rotate to the same orientation, have a battle group of ships follow around a leader command ship, order AI capships to 'attack' an enemy craft by pulling up next to it and rotating 90 degrees to bring broadsides to bear, ordering a ship track a target orientation, and many other things.

Gritty Details
The following custom lua sexps are included:
move-to-orientation and move-to-face-object
Moves a ship to a given orientation over a specified time duration. This sexp only has to be called once and can be used to make a much more natural looking rotational effect for ships. By default this sexp will issue a play-dead-persistent order with priority 200, but this priority value can be changed and the order can also not be issued. Also by default it will use the ship's tabled rotational velocity to make the rotation look natural.

Immediately terminates the custom `move-to-orientation` sexp for a ship. Only use this sexp to prematurely stop `move-to-orientation` for a ship.

Sets a waypoint to a position relative to a ship or waypoint continually. This sexp is an easier way to make a dynamic waypoint track a ship location. The waypoint will be moved to the specified coordinates relative to the ship at every time duration. If the ship is not present or destroyed, or departed then the waypoint will not update location.

Removes a waypoint tracking of a ship. This sexp removes the effect of 'add-waypoint-track-ship'.

Adds a custom ai-goal for a ship to track a waypoint path. The ship will move to the final point in the waypoint path and remain in that position. If the waypoint path is moved the ship will follow the waypoint path again. Useful for having ships follow dynamic waypoints. Note, this order can only be removed via the sexps 'remove-ai-goal-track-waypoint' or 'clear-goals'.

Removes a custom `add-ai-goal-Track-Waypoint` goal.

Sets an idle/resting orientation for a ship tracking a waypoint, either as an absolute orientation or an orientation relative to a given ship. When a ship that is tracking a waypoint is not moving forward it will move to this idle orientation. If a relative orientation is specified the sexp will get the target ship orientation and then add the pitch, bank, and heading values set in this sexp to create a final idle/resting orientation.

Unsets/removes the idle/resting orientation for a ship tracking a waypoint. This sexp will result in a ship tracking a waypoint to not attempt to change it's orientation when not moving.

Adds a custom ai-goal for a ship to track another ship. The ordered ship will move to follow the target ship and then once stopped will rotate to the target ship orientation, or a variant to that orientation. This is a higher level sexp that runs 'add-Waypoint-Track-Ship' with 'add-ai-goal-Track-Waypoint' and 'set-Idle-Track-Orientation'.

Removes a custom ai-goal for a ship to track another ship. This is a higher level sexp that runs 'remove-waypoint-track-ship' with 'remove-ai-goal-track-waypoint' and 'unset-idle-track-orientation'.

Sets the bank constant of a given ship. Bank constant is the amount of roll (bank) a ship does when turning (yawing).

Sets the deceleration time of a given ship. Setting this to 0 will ensure that ships stop precisely at waypoints. Note, stopping may look a bit rigid if the ship is going very fast.

Download these two files from and then place them in your data/tables folder. Then just open FRED and you will see a new listing called LUA-Movements where all the sexps are located. There are detailed descriptions of each sexp and each argument.

Important! You need an FSO build of August 24, 2022 or newer for these to work.

I included an example mission that shows how to use the 'move-to-orientation' and the 'add-ai-goal-track-ship' which is a higher order sexp that runs 'add-waypoint-track-ship' with 'add-ai-goal-track-waypoint' and 'set-idle-track-orientation'.

Change Log

--- Code: ---v2.5: Updated internal code with some cleanup and extra error checking.
v2.4: Added `set-pos-to-rand-pos-in-b-box` lua sexp.
v2.3: Minor optimization and code cleanup. Also added `get-waypoint-speed-cap` and `set-pos-to-rand-pos-on-hull` lua sexps. 
v2.2: add new sexp 'move-to-face-object` and expanded ability of `add-waypoint-track-ship`.
v2.1: add semi-smart waypoint follow option.
v2.0: updated default rotation to fully use FSO ship AI, so rotations now look completely natural if using the default rotation time.
v1.8: added new sexps for precise big ship physics and changed default to not enable play-dead-persistent.
v1.7: Added safety checks to ensure scripts do not run in multiplayer.
v1.6: Fixed default calculation of ship tracking distance if none was specified.
v1.5: Fixed bug with auto turning time calculation.
v1.4: Exposed some more options to the user.
v1.3: Fixed occasional ship spinning occurrences.
v1.2: Added extra error checking for a few spots and more helpful debug messages.
v1.1: Added track orientation behavior. Now ships will also maintain the specified orientation to their specified target, even if the target rotates or moves. Thanks for the suggestion General Battuta!
v1.0: First release.

--- End code ---

Finally, I would be happy to answer any questions and hope you can find something that is useful for your own missions!

Very cool. I almost certainly have use for some of these.

Great! If there is any extra functionality you wanted added that may be useful just let me know.

Good work! :)

General Battuta:

--- Quote from: wookieejedi on December 01, 2019, 10:02:08 am ---Great! If there is any extra functionality you wanted added that may be useful just let me know.

--- End quote ---

My holy grail of movement SEXPs is 'hold relative orientation' (or 'hold relative aspect' or whatever). Tells a ship to position itself in a point, say, 500 meters beneath the target's origin, maintain that point relative to the target no matter how the target maneuvers, and hold its own orientation respect to the target.

Or, in other words: "go to 500 below the target's origin and keep your top facing that origin no matter what."

Probably really hard.


[0] Message Index

[#] Next page

Go to full version