Activator Action System

Create interactive worlds using activators and actions in the unity editor. Activators are things triggered usually by some user action, they can then chain into logical activators and ultimately activators can trigger actions.

Since the original system was created within 3 days with a specific goal in mind - creating a dungeon with traps and basic puzzles - the system is fairly limited, however whatever you do with it you at the very least don’t have to think about syncing, it should just work (so long as you don’t disable scripts part of this system).

Due to the nature of how the system works - each activator and action being an individual component - it likely does not scale well. You can attempt to give the game objects somewhat descriptive names, but at the end of the day it requires a lot of clicking around in the hierarchy to understand what some logic setup might be doing.

About Local Only

The PlayerTriggerActivator has a local only option, which pretty much goes against the point of the entire system. The point being it always being in sync. However realistically the system is already capable of a decent amount of things, so might as well allow some parts of it being for the local player only - effectively desynced.

Installing

Head to my VCC Listing and follow the instructions there.

Contributing

This project uses custom git filters to reduce the amount of noise generated by Udon and UdonSharp. These filters are not required in order to contribute, though without them all UdonSharp asset files will show as modified and those “changes” should not be committed.

Important

• Do not disable scripts part of this system, it would break syncing. For toggle-able interacts use the InteractProxy from the JanSharp Common package
• The initial state of the world is evaluated at build time and applied/enforced on Start. Read more

Samples

This packages includes one sample which includes animation controller bases you could use for actions that require animations. To get the sample, in unity on the menu bar go to Window => Package manager => In Project (top left) => Action Activator System => Samples.

Note the use of Write Defaults in the animation states, I recommend reading the documentation for it to understand what it does. The reason why the loop toggle animation controller is using it on the default state is to reset the state to default when it gets deactivated, otherwise it may freeze somewhere in the middle. However that may be desired behaviour, in which case you can uncheck the checkbox. In the case for the one time animation it should always be enabled on the default state, at least in all cases I can think of. For every other state it is disabled.

Technically we shouldn’t use Write Defaults at all, see here, although that page is specifically for avatars so I’m not even sure if it applies to worlds. Even still, the argument that it makes the animations more maintainable is very reasonable. In this case, since the sample animations are so tiny and I’m not actually providing sample animations, only the controller, I can’t really provide you with “reset” animations. If you want to follow the workflow of always having Write Defaults disabled you’ll have to add a reset animation that’s a single frame long that “animates” the properties that get modified by the other animation in the controller to their default value, so both frame 0 and 1 in said reset animation have the same values. I’d definitely recommend doing this for bigger animation controllers. (Do note that I’m no expert with animations, but I believe what I just described does work.)

Activators

All activators have 2 states: on and off.

User Interactive Activators

• ToggleActivator (levers)
• ButtonActivator (DM buttons, maybe something else)
• PlayerTriggerActivator (pressure plates, trip wire and proximity triggers)
• ItemTriggerActivator (item slots)

Logical Activators

• LogicalANDActivator (active when all input activators are active)
• LogicalORActivator (active when any input activator is active)
• LogicalXORActivator (active when only one input activator is active)
• LogicalNOTActivator (inverts the state of the referenced activator)
• MemoryActivator (The memory activator will reference 2 activators. An enable and a reset activator. When the enable activator activates the memory activator also activates. The enable activator deactivating gets ignored so the memory activator stays on. Then when the reset activator activates the memory activator deactivates and stays inactive.)
• ClockActivator (Emits a pulse every x seconds while the input activator is active. The input activator disabling merely pauses the clock, there is no way to reset it.)
• OnStartActivator (Emits a pulse in Start. Likely hardly useful, however due to changes in the system this was previously doable using a LogicalNotActivator, which is no longer the case. So this activator only exists for legacy reasons in case any system was depending on this old behavior.)

Activator Events

• OnActivate
• OnDeactivate
• OnStateChanged

Actions

Actions can listen to and trigger on any of the activator’s events.

Stateless Actions

Stateless actions simply trigger on an event. Stateless actions are meant to be very short, like a few seconds.

• TriggerAnimationAction (animation with a trigger parameter. Spear wall traps might use this, though they might instead use ToggleAnimationAction)
• AudioAction
• ParticleAction
• MovementAction (move an object with the position sync script on it x units along some axis. Stateless because the position sync script is handling the state.)
• DropItemAction (drop one specific VRC_Pickup)

Stateful Actions

Stateful actions reflect the state of a referenced activator, which means they can only ever have 2 states.

• ToggleAnimationAction (animation with a bool parameter - the state. For levers, trap doors)
• (animation loop) (can be done using ToggleAnimationAction)
• AudioLoopAction
• ParticleLoopAction
• ToggleGameObjectAction (doesn’t actually directly reflect the state, simply toggles game objects’s active state whenever the activator’s state changes. technically could be done using animations but this is much simpler)

Other Scripts

• ObjectPositionSync, required by MovementAction
• DM Toggle to show/hide DM only activators
  • ToggleActivator and ButtonActivator - use an InteractProxy (from the JanSharp Common package) to pass the Interact event from a locally togged object to the actual activator, since those activators must always be active
  • PlayerTriggerActivator and ItemTriggerActivator - cannot be made DM only because it breaks syncing, since that’s based on local positions and trigger events

Initial state

The initial state of the map - activators and actions contained with in it - is evaluated at build time (upon entering play mode or building/publshing the world).

Stateful actions are going to apply this evaluated initial state on Start if the objects they are managing don’t already match said state.

Syncing

Synced scripts are

• ObjectPositionSync
• ToggleActivator
• ButtonActivator
• MemoryActivator

PlayerTriggerActivator and ItemTriggerActivator are synced through the position of the object entering the trigger zone. It might cause scuff but trying to work around it is like stupid difficult. And the rest is simply evaluated by every client locally.