The editor (right) and the runtime (left).
+ +The editor and runtime communicate with each other via a WebSocket connection. When you make changes in the editor, the changes are sent to the runtime, which then updates the scene accordingly. This architecture allows you to see the changes you make in real-time. Conversely, when you make changes in the runtime (e.g., changing a node's data input programmatically), the changes need to be sent back to the editor (see [Accessing Data Inputs](ports-and-triggers#accessing-data-inputs)). + +The Warudo runtime is built using [Unity 2021.3](https://unity.com/); however, the core framework is designed to be as engine-agnostic as possible, which allows nodes, assets, and plugins to interact with each other and with the user through a set of simple and clean APIs, as well as enabling features such as [hot-reloading](../playground). + +Instead of writing C# classes that derive from `MonoBehaviour` in typical Unity projects, you will write classes that derive from Warudo's base classes such as `Node` and `Asset`. These classes are then instantiated and managed by Warudo's runtime. Then, inside these classes, you can call Unity APIs to interact with the Unity scene, such as creating GameObjects, adding components, etc. + +
+
+
+Note how they are initialized with the default values we specified in the code. These default values will be assigned to the data input again when the user clicks the "Reset" button next to the data input label.
+
+A data input typically has a serializable type ("serializable" here means that the data value can be saved and restored when Warudo is closed and reopened). The following types are serializable by default:
+
+- Primitive types: `int`, `float`, `bool`, `string`, any Enum type
+- Unity types: `Vector2`, `Vector3`, `Vector4`, `Color`
+- [Structured data](structured-data.md) types
+- [Asset references](#asset-references)
+- Arrays of serializable types
+
+For nodes, it is possible to define non-serializable data inputs that cannot be edited in the editor but instead processed by the node itself. For example, the following code calls the `ToString()` method on the generic `object` data input:
+
+```csharp
+[NodeType(Id = "dc28819e-5149-4573-945e-40e81e2874c4", Title = "ToString()", Category = "CATEGORY_ARITHMETIC")]
+public class ToStringNode : Node {
+
+ [DataInput]
+ public object A; // Not serialized
+
+ [DataOutput]
+ [Label("OUTPUT_STRING")]
+ public string Result() {
+ return A?.ToString();
+ }
+
+}
+```
+
+Other common data input types that are not serializable but can be passed between nodes include `Dictionary`, `GameObject` and `Quaternion`.
+
+### Attributes {#data-input-attributes}
+
+Data input ports can be annotated with attributes to provide additional context to the editor. For example, the `[IntegerSlider]` attribute we saw earlier specifies that the data input should be displayed as a slider with a range of 1 to 100. Here are the supported attributes:
+
+- `[Label(string label)]`: Specifies the label of the data input.
+- `[HideLabel]`: Specifies that the label of the data input should be hidden.
+- `[Description(string description)]`: Specifies the description of the data input.
+- `[HiddenIf(string methodName)]`: Specifies that the data input should be hidden if the specified method returns `true`. The method must be a `public` or `protected` method in the entity class that returns a `bool`.
+ ```csharp
+ [DataInput]
+ public int MyNumber = 0;
+
+ [DataInput]
+ [HiddenIf(nameof(IsSecretDataInputHidden))]
+ public string SecretDataInput = "I am hidden unless MyNumber is 42!";
+
+ public bool IsSecretDataInputHidden() => MyNumber != 42;
+ ```
+- `[HiddenIf(string dataInputPortName, If @if, object value)]`: Specifies that the data input should be hidden if the specified data input port satisfies the `@if` condition. The value must be a constant.
+ ```csharp
+ [DataInput]
+ public int MyNumber = 0;
+
+ [DataInput]
+ [HiddenIf(nameof(MyNumber), If.NotEqual, 42)]
+ public string SecretDataInput = "I am hidden unless MyNumber is 42!";
+ ```
+- `[HiddenIf(string dataInputPortName, Is @is)]`: Specifies that the data input should be hidden if the specified data input port satisfies the `@is` condition.
+ ```csharp
+ [DataInput]
+ public CharacterAsset MyCharacter;
+
+ [DataInput]
+ [HiddenIf(nameof(MyCharacter), Is.NullOrInactive)]
+ public string SecretDataInput = "I am hidden unless MyCharacter is selected and active!";
+ ```
+- `[DisabledIf(...)]`: Similar to `[HiddenIf(...)]`, but the data input is disabled instead of hidden.
+- `[Hidden]`: Specifies that the data input should be always hidden. This is useful when you want to use a data input in code but not expose it to the user.
+- `[Disabled]`: Specifies that the data input should be always disabled (non-editable). This is useful for array data inputs that have a constant length, or for visualizing data inputs that are always programmatically set, etc.
+- `[Section(string title)]`: Specifies that the data input and all subsequent data inputs should be displayed in a new section with the specified title, unless another section is specified.
+- `[SectionHiddenIf(string methodName)]`: Requires attribute `[Section]`. Specifies that the section should be hidden if the specified method returns `true`. The method must be a `public` or `protected` method in the entity class that returns a `bool`. The `@if` and `@is` conditions are also supported.
+- `[Markdown(bool primary = false)]`: Specifies that the data input should be displayed as a Markdown text and cannot be edited. The data input must be of type `string`. If `primary` is `true`, the text will be displayed in a larger font size without a color background.
+
+:::info
+`[HiddenIf]` and `[DisabledIf]` attributes are evaluated every frame when the asset or node is visible in the editor. Therefore, you should avoid using expensive operations in these methods.
+:::
+
+Some attributes are specific to certain data input types:
+- `[IntegerSlider(int min, int max, int step = 1)]`: Requires data type `int` or `int[]`. Specifies that the data input should be displayed as an integer slider with the specified range.
+- `[FloatSlider(float min, float max, float step = 0.01f)]`: Requires data type `float` or `float[]`. Specifies that the data input should be displayed as a float slider with the specified range.
+- `[AutoCompleteResource(string resourceType, string defaultLabel = null)]`: Requires data type `string`. Specifies that the data input should be displayed as an auto-complete list of resources of the specified type. For example, the "Character → Default Idle Animation" data input is defined as `[AutoCompleteResource("CharacterAnimation")]`. Please refer to the [Resource Providers & Resolvers](resource-providers-and-resolvers.md) page for more information.
+- `[AutoCompleteList(string methodName, bool forceSelection = false, string defaultLabel = null)]`: Requires data type `string`. Specifies that the data input should be displayed as a dropdown menu generated by the specified method. The method must be a `public` or `protected` method in the entity class that returns a `UniTask
+
+
+
+
+
+
+You can then access ports and triggers of the referenced asset:
+
+```csharp
+[FlowInput]
+public Continuation Enter() {
+ if (MyCharacter.IsNonNullAndActive()) {
+ MyCharacter.EnterExpression("Joy", transient: true); // Make the character smile!
+ }
+ return Exit;
+}
+```
+
+:::tip
+You can check if the asset is `null` or inactive by using `asset.IsNullOrInactive()`, and vice versa, `asset.IsNonNullAndActive()`.
+:::
+
+What if you want to filter the list of assets shown in the dropdown? You can use the `[AssetFilter(string methodName)]` attribute to specify a method that is used to filter the assets in the scene. The method must be a `public` or `protected` method that receives a parameter of the asset type and returns a `bool`. For example:
+
+```csharp
+[DataInput]
+[AssetFilter(nameof(FilterCharacterAsset))]
+public CharacterAsset MyCharacter;
+
+protected bool FilterCharacterAsset(CharacterAsset character) {
+ return character.Active; // Only show active characters
+}
+```
+
+### Accessing Data Inputs Programmatically {#accessing-data-inputs}
+
+Let's say you have an entity. There are two ways to read its data inputs:
+
+1. Access the data input field directly. For example, if you have a node with a _public_ data input field `public int MyNumber = 42;`, you can read the value of `MyNumber` directly by using `node.MyNumber`.
+2. Use the `T GetDataInput
+
+
+
+
+
+
+When you select a resource URI, Warudo invokes the corresponding **resource URI resolver** to load the resource data. For example, a `.vrm` file and a `.warudo` file can be loaded by two different resolvers, but both resolvers return a `GameObject` (which is the character loaded into the Unity scene), so the character asset can treat them the same way.
+
+Note that resource providers and resolvers must be registered by a [plugin](plugins).
+
+## Provider
+
+Let's go through a toy plugin example to register a custom resource provider that provides prop resources which are just cubes and spheres.
+
+```csharp
+using System;
+using System.Collections.Generic;
+using Warudo.Core;
+using Warudo.Core.Attributes;
+using Warudo.Core.Plugins;
+using Warudo.Core.Resource;
+
+[PluginType(
+ Id = "hakuyatira.primitiveprops",
+ Name = "Primitive Props",
+ Description = "A simple plugin that registers primitive props.",
+ Version = "1.0.0",
+ Author = "Hakuya Tira",
+ SupportUrl = "https://docs.warudo.app")]
+public class PrimitivePropsPlugin : Plugin {
+
+ protected override void OnCreate() {
+ base.OnCreate();
+ Context.ResourceManager.RegisterProvider(new PrimitivePropResourceProvider(), this);
+ }
+
+}
+
+public class PrimitivePropResourceProvider : IResourceProvider {
+ public string ResourceProviderName => "Primitives"; // The name of your provider
+
+ public List
+
+
+
+
+
+Note that you do not need to assign a value to the structured data field as it will be automatically instantiated when the entity is created. That means you can access the structured data's data inputs directly:
+
+```csharp
+public override void OnCreate() {
+ base.OnCreate();
+ MyTransform.ResetAll();
+}
+```
+
+## Components
+
+A structured data type can define data inputs and triggers.
+
+
+
+
+
+
+
+## Lifecycle
+
+A structured data only has one additional lifecycle event `OnUpdate()`, other than the standard lifecycle events (e.g., `OnCreate()`) listed on the [Entities](entities#lifecycle) page.
+
+:::tip
+Structured data are best thought as data containers, so you should not perform complicated logic inside them. It is recommended to keep structured data as simple as possible and let the parent entity handle the heavy lifting.
+:::
+
+## Updating Structured Data
+
+Structured data are just entities, so you can update their data inputs like any other entity:
+
+```csharp
+MyTransform.SetDataInput(nameof(MyTransform.Position), new Vector3(1, 2, 3), broadcast: true);
+
+// or
+
+MyTransform.Position = new Vector3(1, 2, 3);
+MyTransform.BroadcastDataInput(nameof(MyTransform.Position));
+```
+
+When updating multiple data inputs, you can also just assign to the fields directly, and use the `Broadcast` method to broadcast all data inputs at once:
+
+```csharp
+MyTransform.Position = new Vector3(1, 2, 3);
+MyTransform.Rotation = new Vector3(0, 0, 0);
+MyTransform.Scale = new Vector3(1, 1, 1);
+MyTransform.Broadcast(); // Or BroadcastDataInput(nameof(MyTransform));
+```
+
+## Nested Structured Data
+
+Structured data can be nested:
+
+```csharp
+public class MyData1 : StructuredData {
+ [DataInput]
+ public MyData2 NestedData;
+
+ public class MyData2 : StructuredData {
+ [DataInput]
+ public MyData3 NestedData;
+
+ public class MyData3 : StructuredData {
+ [DataInput]
+ public bool SuperNestedBool;
+ }
+ }
+}
+```
+
+## Arrays
+
+You can also define arrays of structured data:
+
+```csharp
+[DataInput]
+public MyTransformData[] MyTransforms;
+```
+
+Note you do not need to initialize the array. Warudo will automatically initialize an empty array:
+
+
+
+
+
+
+
+When the user clicks the **+** button, structured data elements are appended to the array:
+
+
+
+
+
+
+
+## Custom Initializer
+
+Elements in a structured data array are automatically initialized by Warudo:
+
+```csharp
+[DataInput]
+public MyTransformData[] MyTransforms; // Each MyTransforms[i].Scale is initialized to (1, 1, 1)
+```
+
+However, sometimes you may want to initialize the new element with dynamic values. We can use the `[StructuredDataInitializer]` attribute to specify a method that will be called to initialize the structured data:
+
+```csharp
+[DataInput]
+[StructuredDataInitializer(nameof(InitializeTransform))]
+public MyTransformData[] MyTransforms;
+
+protected void InitializeTransform(MyTransformData transform) {
+ transform.Position = new Vector3(Random.value, Random.value, Random.value);
+ transform.Rotation = new Vector3(Random.value, Random.value, Random.value);
+ transform.Scale = new Vector3(Random.value, Random.value, Random.value);
+ // Note there is no need to broadcast - the structured data has not be sent to the editor anyway
+}
+```
+
+When the user clicks the **+** button, the `InitializeTransform` method is called to initialize the new structured data element.
+
+## Programmatically Creating Structured Data
+
+To manually populate the structured data array, or to add structured data elements programmatically, use the `StructuredData.Create
+
+
+
+
+
+You only need to implement the `ICollapsibleStructuredData` interface:
+
+```csharp
+public class MyTransformData : StructuredData, ICollapsibleStructuredData {
+ // ...
+
+ public string GetHeader() => Position + " " + Rotation + " " + Scale;
+}
+```
+
+You can use the `CollapsedSelf` and `CollapsedInHierarchy` properties to determine whether the structured data is collapsed. For example, you can toggle the visibility of a GameObject in the Unity scene based on the structured data's collapsed state:
+
+```csharp
+public override void OnUpdate() {
+ base.OnUpdate();
+ gameObject.SetActive(!CollapsedInHierarchy);
+}
+```
+
+## Accessing Parent Entity
+
+If you need to access the parent entity from the structured data, you can change the base class to `StructuredData
+
+
+
+
+
+## Step 4: Export the Plugin Mod
+
+We are almost done! Before exporting the mod, you can check the mod settings are correct in **Warudo → Mod Settings**. You can set the mod's name, version, author, and description, which should be the same as the `[PluginType]` parameters.
+
+By default, the **Mod Export Directory** is empty; in this case, the mod will be exported to the project's root folder. You can instead set it to the `Plugins` directory in Warudo's data folder, for example `C:\Program Files (x86)\Steam\steamapps\common\Warudo\Warudo_Data\StreamingAssets\Plugins`.
+
+:::warning
+Before exporting, close Warudo and delete `HelloWorldNode.cs` and `CookieClickerAsset.cs` from the `Playground` directory. This is to prevent conflicts between the Playground and the plugin mod.
+:::
+
+Select **Warudo → Export Mod** to export the plugin mod. If everything goes well, you should see a `BUILD SUCCEEDED!` message in the console:
+
+
+
+It is good to perform a sanity check to ensure the scripts in the mod folder are indeed compiled into the plugin mod. Scroll up in the console, and you should find the following line:
+
+
+
+:::warning
+If you do not see this line, your Unity project may not have been set up for C# scripting correctly. Please follow the steps in [this section](../modding/mod-sdk#custom-scripts) and try exporting the plugin mod again.
+:::
+
+Make sure the exported `HelloWorldPlugin.warudo` folder is in the `Plugins` directory in Warudo's data folder. You can now open Warudo and check if the plugin mod is loaded in the About dialog:
+
+
+
+And of course, the Cookie Clicker asset is now in the **Add Asset** menu, along with the Hello World node in the node palette:
+
+
+
+
+
+Voilà! Your first plugin mod in Warudo!
+
+## Step 5: Load An Unity Asset
+
+Now that you have a plugin mod, you can load custom Unity assets into Warudo! Let's try loading a Unity asset in the `CookieClickerAsset` script.
+
+Download [Cartoon FX Remaster Free](https://assetstore.unity.com/packages/vfx/particles/cartoon-fx-remaster-free-109565) from the Unity Asset Store. Import the package into your Unity project. Then, select a particle prefab from the package, hold **Ctrl**, and drag it into the "HelloWorldPlugin" folder. We will use the "CFXR Explosion 1" prefab in this example.
+
+
+
+Rename the prefab into `Particle`. Your mod folder should now look like this:
+
+
+
+Open the `CookieClickerAsset.cs` script and replace with below:
+
+```csharp
+using System;
+using Cysharp.Threading.Tasks;
+using UnityEngine;
+using Warudo.Core.Attributes;
+using Warudo.Core.Scenes;
+using Object = UnityEngine.Object;
+using Random = UnityEngine.Random;
+
+[AssetType(Id = "82ae6c21-e202-4e0e-9183-318e2e607672", Title = "Cookie Clicker")]
+public class CookieClickerAsset : Asset {
+
+ [Markdown]
+ public string Status = "You don't have any cookies.";
+
+ [DataInput]
+ [IntegerSlider(1, 10)]
+ [Description("Increase me to get more cookies each time!")]
+ public int Multiplier = 1;
+
+ private int count;
+ private GameObject particlePrefab; // New field to store the particle prefab
+
+ [Trigger]
+ public async void GimmeCookie() { // Note the async keyword
+ count += Multiplier;
+ SetDataInput(nameof(Status), "You have " + count + " cookie(s).", broadcast: true);
+
+ // Spawn the particle prefab Multiplier times
+ for (var i = 0; i < Multiplier; i++) {
+ var particle = Object.Instantiate(particlePrefab, Random.insideUnitSphere * 2f, Quaternion.identity);
+ particle.SetActive(true);
+ Object.Destroy(particle, 3f); // Automatically destroy the cloned particle after 3 seconds
+
+ await UniTask.Delay(TimeSpan.FromSeconds(0.2f)); // Delay 0.2 seconds before spawning the next particle
+ }
+ }
+
+ protected override void OnCreate() {
+ base.OnCreate();
+ SetActive(true);
+
+ // Load the particle prefab from the mod folder. Change this path if your prefab is in a different folder
+ particlePrefab = Plugin.ModHost.Assets.Instantiate
+
+
+
+