Hard Light Productions Forums

FreeSpace Releases => Scripting Releases => Topic started by: wookieejedi on November 30, 2019, 07:28:35 pm

Title: Movements-SEXPs, capship useful (v2.5)
Post by: wookieejedi on November 30, 2019, 07:28:35 pm
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)

(https://cdn.discordapp.com/attachments/223511363807346691/650508690113167426/unknown.png)


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

Background
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!


Overview
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.

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

add-waypoint-track-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.

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

add-ai-goal-track-waypoint
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'.

remove-ai-goal-track-waypoint
Removes a custom `add-ai-goal-Track-Waypoint` goal.

set-idle-track-orientation
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.

unset-idle-track-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.

add-ai-goal-track-ship
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'.

remove-ai-goal-track-ship
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'.

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

set-deceleration-time
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.


Usage:
Download these two files from https://github.com/wookieejedi/FSO-Scripts/tree/master/Movements-SEXPs (https://github.com/wookieejedi/FSO-Scripts/tree/master/Movements-SEXPs) 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: [Select]
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.

Finally, I would be happy to answer any questions and hope you can find something that is useful for your own missions!
Title: Re: Release of Movements-SEXPs (v1.0 Nov 30, 2019)
Post by: mjn.mixael on November 30, 2019, 08:10:36 pm
Very cool. I almost certainly have use for some of these.
Title: Re: Release of Movements-SEXPs (v1.0 Nov 30, 2019)
Post by: 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.
Title: Re: Release of Movements-SEXPs (v1.0 Nov 30, 2019)
Post by: Nightmare on December 01, 2019, 01:27:13 pm
Good work! :)
Title: Re: Release of Movements-SEXPs (v1.0 Nov 30, 2019)
Post by: General Battuta on December 01, 2019, 05:06:46 pm
Great! If there is any extra functionality you wanted added that may be useful just let me know.

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.
Title: Re: Release of Movements-SEXPs (v1.0 Nov 30, 2019)
Post by: wookieejedi on December 01, 2019, 06:19:06 pm
Great! If there is any extra functionality you wanted added that may be useful just let me know.

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.


Alright, just added that functionality (github also updated). That is now the default behavior for `add-ai-goal-track-ship` and you can also turn that behavior on and off using `set-idle-track-orientation`. So now you can really tell a ship to go to a spot relative to another ship and keep it's nose pointed at it no matter what :)
Title: Re: Release of Movements-SEXPs (v1.1 Dec 1, 2019)
Post by: General Battuta on December 06, 2019, 10:43:49 am
Without looking - how do you specify whether you want the mover to aim their nose, top, bottom, or ass at the target? Or is it nose only?
Title: Re: Release of Movements-SEXPs (v1.1 Dec 1, 2019)
Post by: wookieejedi on December 06, 2019, 10:58:28 am
Without looking - how do you specify whether you want the mover to aim their nose, top, bottom, or ass at the target? Or is it nose only?

Good question, the user can specify what direction to aim. The inputs for `add-ai-goal-track-ship` takes, among other things, a pitch, bank, and heading that is relative to the target ship's orientation. So, say you wanted Ship A to pull up beneath Ship B and then rotate so it's butt is facing Ship B. To do that you would set the relative y location in `add-ai-goal-track-ship` to some negative value and then the pitch and heading of 0 and a pitch of 90 degrees (again these are relative to Ship B's orientation). These inputs to the sexp would tell Ship A to go to that position relative to Ship A and then point it's butt up in the air so the butt is facing Ship B.

The full sexp and all it's arguments for that higher order sexp are:
Code: [Select]
$Operator: add-ai-goal-track-ship
$Category: Change
$Subcategory: LUA-Movements
$Minimum Arguments: 3
$Maximum Arguments: 10
$Return Type: Nothing
$Description: 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'. This sexp uses a time interval of 1 second for updating positional data and a track distance of the radius of the ship following the track order. Note, use a waypoint path with only 1 waypoint. The order 'clear-goals' will also stop this custom order. Also the ship will continually maintain the specified orientation when at rest.
$Parameter:
+Description: Ship to order.
+Type: Ship
$Parameter:
+Description: Target ship to track.
+Type: Ship
$Parameter:
+Description: Waypoint path to use for the ship to follow.
+Type: Waypointpath
$Parameter:
+Description: Priority of order. Default is 100.
+Type: Number
$Parameter:
+Description: X offset in meters from the center of the target ship that the ordered ship will move to. Default is random value between the radius and diameter of the target ship.
+Type: Number
$Parameter:
+Description: Y offset in meters from the center of the target ship that the ordered ship will move to. Default is random value between the radius and diameter of the target ship.
+Type: Number
$Parameter:
+Description: Z offset in meters from the center of the target ship that the ordered ship will move to. Default is random value between the radius and diameter of the target ship.
+Type: Number
$Parameter:
+Description: Pitch of idle orientation in degrees relative to target ship orientation. Default is 0 (same pitch as target). Any value is valid and will be converted to range within 0-359.
+Type: Number
$Parameter:
+Description: Pitch of idle orientation in degrees relative to target ship orientation. Default is 0 (same bank as target). Any value is valid and will be converted to range within 0-359.
+Type: Number
$Parameter:
+Description: Pitch of idle orientation in degrees relative to target ship orientation. Default is 0 (same heading as target). Any value is valid and will be converted to range within 0-359.
+Type: Number
Title: Re: Release of Movements-SEXPs (v1.1 Dec 1, 2019)
Post by: General Battuta on December 06, 2019, 12:39:35 pm
Fantastique! This will be amazing for capship choreography, especially in capship command missions.
Title: Re: Release of Movements-SEXPs, capship useful (v1.1 Dec 1, 2019)
Post by: wookieejedi on December 06, 2019, 04:26:36 pm
Thanks, glad it will be helpful. If you or anyone else comes across anything that you’d like added just let me know and I can see what I can do!
Title: Re: Release of Movements-SEXPs, capship useful (v1.1 Dec 1, 2019)
Post by: 0rph3u5 on December 06, 2019, 04:30:14 pm
I am certainly going to get some use out of these for Pendragon - even though my stated goal is to get rid of capital ships more and more...
Title: Re: Release of Movements-SEXPs, capship useful (v1.2 Dec 28, 2019)
Post by: wookieejedi on December 28, 2019, 10:16:12 am
Excellent! Also I just updated the main -sct file on github. V1.2 provides additional validity checks for certain functions and more helpful debug messages.
Title: Re: Release of Movements-SEXPs, capship useful (v1.2 Dec 28, 2019)
Post by: Nightmare on December 28, 2019, 12:12:40 pm
Sorry to bump here, but what would you think of having a common HLP scripting repo on github or elsewhere?
Title: Re: Release of Movements-SEXPs, capship useful (v1.2 Dec 28, 2019)
Post by: wookieejedi on December 28, 2019, 12:18:29 pm
No worries, I'd say that's a good idea. Even just a stickied board where there are links to active scripters's githubs could work, too. Perhaps opening up a topic and getting other's feedback would be beneficial, too.
Title: Re: Release of Movements-SEXPs, capship useful (v1.2 Dec 28, 2019)
Post by: Nightmare on December 28, 2019, 12:19:28 pm
Will do!
Title: Re: Release of Movements-SEXPs, capship useful (v1.2 Dec 28, 2019)
Post by: wookieejedi on January 01, 2020, 01:16:51 pm
Note, updated script to version 1.3, which fixes occasional ship spinning occurrences.
Title: Re: Release of Movements-SEXPs, capship useful (v1.3 Jan 01, 2020)
Post by: EatThePath on May 07, 2020, 12:10:09 pm
These seem very useful, thank you for making them. I have some questions, though.

What is relative orientation relative to? Are you setting what where ship A is going to point it's nose relative to it's vector to ship B, or are you setting ship A's orientation to be an offset to ship B? I can imagine both being useful, the former for things like broadside fighting and the latter for holding formations of ships. I think you can probably ultimately accomplish both with either, but some are more straight-forward to use in certain ways than others.

With relative position offsets for tracking, does that relative position account for the orientation of the target ship as well, or is it in defaultly oriented coordinates just centered on the tracked ship?

Lastly, I find myself wanting a version of ai-goal-track that takes a distance rather than a vector for positional offset.
Title: Re: Release of Movements-SEXPs, capship useful (v1.3 Jan 01, 2020)
Post by: wookieejedi on May 07, 2020, 12:34:22 pm
Thanks, and all good questions.

What is relative orientation relative to?

Relative orientation is relative strictly to the target's orientation (so an offset to ship B). For example, if you want Ship A to be broadsides against Ship B then you would tell the sexp to use relative orientation and set the heading value as 90. Ship A will move to the waypoint, then rotate to an orientation that is 90 degrees different than Ship B.

Yes, relative position offsets account for the target ship's direction. So if you want Ship A to follow right behind Ship B then make the offset have a z value of some negative number. For example, if I set it to -300 for the z offset it will be 300 meters behind the ship, no matter what orientation that target ship is in.

For your last point, I think I see what you mean, but could you give an example just so I am sure?
Title: Re: Release of Movements-SEXPs, capship useful (v1.3 Jan 01, 2020)
Post by: EatThePath on May 07, 2020, 12:41:13 pm
For examples example, say I want a Ravana fly to 2000 m away from a target and point it's nose at that target, without caring if the target is twisting around itself, or a moloch to hold a broadside at a specific distance in a similar situation.
Title: Re: Release of Movements-SEXPs, capship useful (v1.3 Jan 01, 2020)
Post by: wookieejedi on May 07, 2020, 02:09:15 pm
For examples example, say I want a Ravana fly to 2000 m away from a target and point it's nose at that target, without caring if the target is twisting around itself, or a moloch to hold a broadside at a specific distance in a similar situation.

Ah I see, thank you for the examples. That would indeed be useful, and I have added that as an option in v1.4. There are two options to set to achieve that behavior. The sexp `ai-goal-track` now has two additional optional arguments to set to achieve that kind of behavior.



Also the option to disable or set the priority of the play_dead order used during ship rotations as also been added to the ship_track_ship sexp.
Title: Re: Release of Movements-SEXPs, capship useful (v1.5 May 17, 2020)
Post by: wookieejedi on May 17, 2020, 02:00:34 pm
Updated to Version 1.5 which provides a very important bug fix for doing the automatic rotation time calculation. Also re configured script to run in $Simulation Hook per m!m's suggestion.
Title: Re: Release of Movements-SEXPs, capship useful (v1.5 May 17, 2020)
Post by: wookieejedi on June 11, 2020, 08:57:27 am
Updated to version 1.6 which correctly calculates the default distance for ship tracking if the value was not specified. Thanks for EatThePath for catching this!
Title: Re: Release of Movements-SEXPs, capship useful (v1.7 June 10, 2021)
Post by: wookieejedi on June 10, 2021, 08:49:39 am
Updated to version 1.7, which adds safety checks to ensure these scripts do not run in multiplayer. Also added to sexp descriptions that custom sexps will not work in multiplayer.
Title: Re: Movements-SEXPs, capship useful (v1.7)
Post by: wookieejedi on August 21, 2022, 01:08:36 pm
Updated to version 1.8 which includes two new custom sexps:

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

"set-deceleration-time"
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.

Also changed the "play-dead-persistent" order to be disabled by default.
Title: Re: Movements-SEXPs, capship useful (v2.0)
Post by: wookieejedi on August 24, 2022, 09:46:55 am
Updated to version 2.0, which fulfills a long-term goal for default ship rotation--that the scripted rotations look identical to regular ship rotations (including momentum and damping). 

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

If you were using default values for rotation times for the custom sexps `rotate-to-orientation` or `add-ai-goal-track-ship` then this update will allow those rotations to look far more natural. 

Previously, this script set ship rotations based on a linear scale for all situations. This was fine if a precise rotation time was needed, but looked a bit rigid and unnatural if a default rotation time was desired. This update adds a new method for using the default rotation time. The overall amount of time the rotation takes is nearly the same, but the rotation looks much more smooth comparatively. This update also keeps the previous behavior and option for precise, specified rotations.

There are use cases for both.
 
Title: Re: Movements-SEXPs, capship useful (v2.0)
Post by: wookieejedi on August 24, 2022, 01:20:00 pm
EDIT: updated with hot-fix for folks who use `continuous-orientation-check` with relatively small distances.
Title: Re: Movements-SEXPs, capship useful (v2.0)
Post by: wookieejedi on August 27, 2022, 07:42:27 am
Updated to version 2.1, which fulfills another long-term goal: Whether or not the ship should stop moving if it is about to hit something large. If set to true the ship will pause the current waypoint order and not resume again until the path is clear. Default value is false (no stopping for obstacles), so current implementation of sexps is still compatible.

Important! You need an FSO build of August 27, 2022 or newer for these to work.
Title: Re: Movements-SEXPs, capship useful (v2.1)
Post by: wookieejedi on September 13, 2022, 01:58:03 pm
Updated to version 2.2 which includes a new sexp and adds more functionality to another existing sexp.

Added `move-to-face-object` which has all the bells and whistles of `move-to-orientation` but is for rotating to face a ship or waypoint, not a specific orientation. Useful if you want one or more cap ships to rotate naturally to face a specific point or another ship. You might say, hey how is this different from the existing sexp 'set-object-facing'? With that sexp you have to call it every frame, and it is difficult to manually tune how long a rotation should take. With this new sexp, set it all once (including a delay, specific rotation time, or default natural rotation time) and let the sexp do the rest of the work for you.

Updated `add-waypoint-track-ship` sexp to now also be able to track another waypoint. The name remains the same for backwards compatibility, though the help text has been updated accordingly. This is useful if you want your waypoints to track other waypoints instead of just ships.

Title: Re: Movements-SEXPs, capship useful (v2.3)
Post by: wookieejedi on January 16, 2023, 09:53:00 pm
Updated to version 2.3:

Added new `get-waypoint-speed-cap` lua sexp.
Returns the current waypoint speed cap of a given ship (the speed that is set with the sexp 'cap-waypoint-speed'). Will return cap speed value if a cap is set, -1 if no cap is set, and 0 if ship is invalid.

Added new `set-pos-to-rand-pos-on-hull` lua sexp.
Chooses a random point on the hull of a given ship and sets the position of the given object to that point.

Updated with minor optimizations and code cleanup.
Title: Re: Movements-SEXPs, capship useful (v2.1)
Post by: Grizzly on January 17, 2023, 03:49:51 am
Added `move-to-face-object` which has all the bells and whistles of `move-to-orientation` but is for rotating to face a ship or waypoint, not a specific orientation. Useful if you want one or more cap ships to rotate naturally to face a specific point or another ship. You might say, hey how is this different from the existing sexp 'set-object-facing'? With that sexp you have to call it every frame, and it is difficult to manually tune how long a rotation should take. With this new sexp, set it all once (including a delay, specific rotation time, or default natural rotation time) and let the sexp do the rest of the work for you.

This sounds utterly lovely!
Title: Re: Movements-SEXPs, capship useful (v2.3)
Post by: Darius on January 17, 2023, 04:07:10 am
The entire package has been a godsend  :yes:
Title: Re: Movements-SEXPs, capship useful (v2.3)
Post by: mjn.mixael on January 17, 2023, 08:14:24 am
Hmmmm

`set-pos-to-rand-pos-on-hull`

Can that work on waypoints?
Title: Re: Movements-SEXPs, capship useful (v2.3)
Post by: wookieejedi on January 17, 2023, 08:47:27 am
Yes, that's the main reason I made it actually  :)
(Behind the scenes reason is that I added repair droids to FotG, and wanted a way for them to pick a random position on a ships hull to fly to, so I set the waypoint position with this sexp, then order them to go to the waypoint).
Title: Re: Movements-SEXPs, capship useful (v2.4)
Post by: wookieejedi on January 17, 2023, 09:50:44 am
Very glad to have it be so useful for folks!


Another quick small update, per request of MjN for an additional sexp.

v2.4:

Added new `set-pos-to-rand-pos-in-b-box` lua sexp.
Chooses a random position within the bounding box of a given ship and sets the position of the given object to that point. Note, the randomly selected position by be inside the ship geometry.
Title: Re: Movements-SEXPs, capship useful (v2.5)
Post by: wookieejedi on November 18, 2023, 11:12:07 am
Updated script to version 2.5 which includes some internal cleanup along with extra error checking to prevent edge case script warnings in-game.