Splitter

Splitter will shortly be released as a Unity Asset, available for purchase in the Unity Asset Store.

News
10/9/2024 - Splitter needs testers! If you are interested in receiving and evaluation copy of Splitter, and wouldn't mind giving some feedback, please send an email to Marc at notime.technology@gmail.com!
About
Splitter is a Unity framework developed by NoTime that can be used to dynamically create and manage isolated physics contexts within Unity's built-in 3d physics engine (NVIDIA PhysX). Isolated physics contexts are extremely useful for wrangling things like:
  • Moving/Rotating platforms
  • Rideable Rigidbodies
  • Explorable Interiors of Moving Vehicles
  • Gravity Walls
  • Any nested combination of the above. For example, an explorable aircraft carrier that rolls in the waves, which has moving platforms on the ship, and is all on a planet that is rotating and moving in space.
How does it work? Splitter provides two components: SplitterAnchor and SplitterSubscriber.
  • SplitterAnchor: The SplitterAnchor component create a 'physics anchor' and defines an isolated physics context. For example, this should be added to moving platforms.
  • SplitterSubscribers: The SplitterSubscriber component gives a rigidbody the ability to interact with SplitterAnchors. For example, this should be added to rigidbodies that need to ride a moving platform.
That's it!
Features
  • Dynamically create and manage isolated physics scenes within Unity's built-in 3d physics engine (NVIDIA PhysX), and use them to control rigidbodies in your scene.
  • Transition rigidbodies to and from isolated physics scenes with smooth executions.
  • Splitter supports physical interaction between rigidbodies in separate physics scenes.
  • Splitter supports nesting isolated physics scenes inside of other isolated physics scenes :).
  • Splitter requires no coding, but does expose useful events and methods if needed.
  • Splitter utilizes the GameObject.SendMessage to provide event level control to programmers.
  • Splitter supports all of the standard Rigidbody applications across physics scenes.
  • Splitter's codebase is source-available! All coding has been done in C# and is exposed as Unity script assets.
  • Splitter provides two systems to handle entry and exit (registration) into isolated physics scenes: trigger-based registration, or manual registration via code.
Getting Started
  • First, purchase the asset here and import all of the contents of the package into your Unity project.
  • Then, open and run the demo scene at [NoTime/Splitter/Demo/Scenes/DemoScene.unity]. It is likely that your use case will be featured in this scene.
  • For a simpler, more straight forward example, open and run the simple example scene at [NoTime/Splitter/Demo/Scenes/SimpleExample]. Follow along with this video for a thorough understanding:
Benchmarking
In Splitter, it is important to note that Subscribers are cheap, and Anchors are expensive. The following benchmarks demonstrate further:
Scene Description Processing Time (Splitter Enabled) Control Processing Time (Splitter Disabled)
100 Subscribers in 1 Anchor 3.60ms 1.78ms
30 pairs of 1 Subscriber in 1 Anchor 11.48ms 0.59ms
Though Anchors are computationally expensive, keep in mind that empty Anchors (Anchors with no Subscribers and no scripts in RunInSimulationSpace) are not simulated, and therefore relatively cheap.
Component Documentation
SplitterAnchor
Creates a 'physics anchor' and defines an isolated physics context.
Tip: The anchor's physical orientation in the isolated physics scene is defined by the anchor's local rotation. If this proves to be confusing, try setting SimulationVisible to true to get a visual representation of the simulated anchor.

List<Collider> EntranceTriggers - A list of triggers that are used to define an entrance area. When a subscriber triggers any of these triggers, the subscriber will be evaluated to be entered into this anchor's isolated physics context. Caveat: See EntrancePriority.

List<Collider> StayTriggers - A list of triggers that are used to define a stay area. As long as a subscriber who has entered this anchor's isolated physics context remains in contact with one of these triggers, the subscriber will continue to be simulated in this anchor's isolated physics context. Caveat: See the EntrancePriority property.
Tip: In general, the entrance triggers should be contained within the StayTriggers. The StayTriggers should be slightly larger than the Entrance triggers. This ensures that there is a buffer zone to prevent jittery rapid entrance/exit of an anchor.
int EntrancePriority - Used to manage nested anchors. Defines the priority this anchor takes over other overlapping anchors. For example, imagine a scene with a boat in an ocean on a rotating planet, where the boat and the planet are both SplitterAnchors. In this case, the entrance priority of the ship should be higher than the planet. This way, if the player is already in the planet's physics simulation, we know it is okay to exit and enter the boat's physics simulation if triggered.
bool SimulationVisible - This is made available for debugging only. If this is true on start, then the simulated anchor will remain visible. All simulated anchors can be found at the world position of Vector3(100, 100, 100).
bool SyncSubscriberTransforms - This provides the most accurate positional syncing at the cost of some cpu processing power. Use this to directly move all associated subscriber's transforms to the exact position and rotation of their simulation at Update. Note: This can be overridden by individual subscribers.
Tip: This feature is most commonly not needed. Usually syncing via Rigidbody interaction (enabled by default) is enough to do the trick.
bool SyncSubscriberChildTransforms - Use this in order to sync simulated updates to the subscribers child transforms. Note: This can be overridden by individual subscribers.
SplitterSubscriber
Gives a rigidbody the ability to interact with SplitterAnchors
List<MonoBehaviour> RunInSimulationSpace - A list of Monobehaviors that should be run in the context of the anchor's simulated space when possible. When a splitter subscriber enter's an anchor, all RunInSimulationSpace scripts are disabled, then reinitialized in the simulation space. When a splitter subscriber exits the anchor, the scripts in the simulation space are destroyed and the initial RunInSimulationSpace scripts are enabled again. One common use for this is for player controls of a physical object.
Tip: This feature has been made available for non-coders to run existing scripts inside of anchor space. Otherwise, it is usually easier for coders to program physical interactions using the SplitterSubscriber.AppliedPhysics class (see below).
NOTE: References to Physics from scripts added to RunInSimulationSpace will not work properly! This is because and physics queries made from the static physics class will be referencing the incorrect (original) scene. One work around is to instead make a similar call from gameObject.scene.GetPhysicsScene(). So, for example, instead of using Physics.Spherecast(...), use gameObject.scene.GetPhysicsScene().Spherecast(...).
bool OverrideAnchorSettings - Once enabled, the Sync Transform and Sync Child Transforms options will effectively override the settings in any associated anchor's Sync Settings. This will only effect this subscriber's behaviour.
bool SyncTransform - This provides the most accurate positional syncing at the cost of some cpu processing power. Use this to directly move the Subscriber's transform to the exact position and rotation of the simulation at Update. Note: This will override associated anchor settings.
Tip: This feature is most commonly not needed. Usually syncing via Rigidbody interaction (enabled by default) is enough to do the trick.
bool SyncChildTransforms - Use this in order to sync simulated updates to the subscribers child transforms. Note: This will override associated anchor settings.
Scripting Documentation
This section contains information on additional Splitter component members that are only accessible via code.
Splitter Subscriber
void ManuallyEnterAnchor(SplitterAnchor Anchor) - Call this function to have the SplitterSubscriber enter the context of the SplitterAnchor. Note that this SplitterSubscriber will now remain in the physics scene of the SplitterAnchor until ManuallyExitAnchor() is called.
void ManuallyExitAnchor() - Call this function to have the SplitterSubscriber exit the current SplitterAnchor (if any). Note that this will only work if it is called after previously calling ManuallyEnterAnchor(SplitterAnchor Anchor).
bool IsSimulating() - Returns true if the SplitterSubscriber is currently registered and simulating in the physics scene of an SplitterAnchor. Otherwise, returns false.
Rigidbody GetSimulationBody() - If this subscriber is currently in a simulation, it will return the Rigidbody of the subscriber within the simulation. Otherwise, returns null. This sort of information is usually not needed, but is made available for convenience.
PreSimulationInstantiation PreSimulationInstantiation - This delegate is executed just before a subscriber is copied into an anchor's simulation. This delegate can be used to make quick alterations to the subscriber before it is copied. See the example below for more information.
PostSimulationInstantiation PostSimulationInstantiation - This delegate is executed just after a subscriber is copied into an anchor's simulation. This delegate can be used to undo alterations to the subscriber before it is copied. The following example will change a subscribers material only in the simulation.
Applied Physics
This class is made accessible to all SplitterSubscribers to provide workflow improvements when applying physical changes to SplitterSubscribers. If a script that makes physics applications to a SplitterSubscriber is not listed in the SplitterSubscribers RunInSimulationSpace<Monobehaviour>, then all physics applications to the SplitterSubscriber MUST be scripted through AppliedPhysics and NOT Rigidbody! Normal Rigidbody methods and properties (i.e. Rigidbody.AddForce(...), Rigidbody.velocity, etc.) will not work when the SplitterSubscriber is in an SplitterAnchor's physical scene, as the SplitterSubscriber's Rigidbody will be controlled by the simulation. Do not use AppliedPhysics in scripts that are listed in RunInSimulation.
This class contains a one-to-one implementation of all Rigidbody members. For example:
player.GetComponent<Rigidbody>().AddForce(transform.forward, 1f);
-becomes-
player.GetComponent<SplitterSubscriber>().AppliedPhysics.AddForce(transform.forward, 1f);

The same goes for properties normally found in the Rigidbody class. For example:
player.GetComponent<Rigidbody>().velocity
-becomes-
player.GetComponent<SplitterSubscriber>().AppliedPhysics.velocity
This is now a more accurate representation of velocity.
Tip: The applied physics class should be used for all subscriber physical interactions, even when the subscriber is not in an anchor!
SplitterEventListener
Provides access to Splitter events.
Some knowledge of the inner workings of Splitter is required when dealing with events. When a subscriber triggers an anchor, a complete copy of the subscriber game object is made and entered into the anchor's physics simulation. The SplitterEventListener's events allow us to access the simulated subscriber and simulated anchor.
To utilize this event listener, have the relevant components inherit from SplitterEventListener instead of MonoBehaviour. Then override any of the following public virtual methods as needed.
Tip: Do you already have an inheritance structure setup? Don't worry. You do not have to explicitly inherit from SplitterEventListener. Simply add a method with the same signature to your Monobehaviour and the splitter system will trigger the event.
OnEnterAnchor(SplitterEvent evt) - Occurs for all components and child components on anchor gameObject. Occurs when the subscriber successfully enters an anchor.
OnExitAnchor(SplitterEvent evt) - Occurs for all components and child components on anchor gameObject. Occurs when the subscriber successfully exits an anchor.
OnSimulationStart(SplitterEvent evt) - Occurs for all components and child components on anchor gameObject. Occurs when the anchor starts simulating a physics context.
OnSimulationCollisionEnter(SplitterEvent evt) - Occurs for all components and child components on subscriber gameObject. Occurs when a simulated subscriber encounters a collision.
OnSimulationCollisionStay(SplitterEvent evt) - Occurs for all components and child components on subscriber gameObject. Occurs when a simulated subscriber collision continues.
OnSimulationCollisionExit(SplitterEvent evt) - Occurs for all components and child components on subscriber gameObject. Occurs when a simulated subscriber exits a collision.
SplitterEvent
This class simply holds relevant information for events.
SplitterAnchor Anchor - The SplitterAnchor associated with the event.
Transform SimulatedAnchor - The transform of the simulated anchor associated with the event.
SplitterSubscriber Subscriber - The SplitterSubscriber associated with the event.
Transform SimulatedSubscriber - The transform of the simulated subscriber associated with the event.
Collision Collision - A Unity Engine Collision object containing all of the relevant info pertaining to collisions that occur inside a simulation. Normal rigidbody collision events still occur, however the values in the Collision argument may be inaccurate. To access accurate collision data, use the SplitterEventListener's correlated event.
Contact
No Time is a small tech and media company located in Lehigh Valley, Pennsylvania, USA.
Questions or Comments? Or just interested? Feel free to contact us!
©NoTime 2024