Package net.risingworld.api.worldelements

Class Prefab

java.lang.Object
net.risingworld.api.worldelements.GameObject
net.risingworld.api.worldelements.Prefab
public class Prefab extends GameObject
Represents a custom prefab. A prefab could consist of multiple models and meshes, and may also contain custom textures and materials, animators, colliders etc. A prefab is typically created in Unity, where you could use almost all Unity components (except "MonoBehaviours"). When using materials or custom shaders, make sure they're HDRP-compatible.

You're also able to change various parameters of any child element of the prefab (i.e a child within the actual prefab asset, not to be confused with another regular GameObject attached to this object).
Example: Load a prefab from an asset bundle
1//Load the asset bundle from plugin folder first
2AssetBundle bundle = AssetBundle.loadFromFile(getPath() + "/assets/MyBundle.bundle");
3
4//Load the prefab asset from asset bundle
5PrefabAsset asset = PrefabAsset.loadFromAssetBundle(bundle, "MyPrefab.prefab");
6
7
8//Create a "Prefab" game object using the asset
9Prefab prefab = new Prefab(asset);
10
11//Set a layer (determines how the player collides with it)
12prefab.setLayer(Layer.DEFAULT);
13
14//Set a position for it - e.g spawn at player position
15prefab.setLocalPosition(player.getPosition());
16
17//Register to player (so it shows up for this player)
18player.addGameObject(prefab);

  • Constructor Details

    • Prefab

      public Prefab()

    • Prefab

      public Prefab(PrefabAsset prefab)

  • Method Details

    • setPrefab

      public void setPrefab(PrefabAsset prefab)
      Assigns a prefab asset to this game object.
      Parameters:
      prefab -

    • setActive

      public void setActive(String path, boolean set)
      Toggles the active state of the prefab or a child of the prefab. Setting this to false will disable the object in the game scene, i.e it is no longer visible and no longer collides with the player or the world. This automatically affects all child elements as well.
      By default, an object is set to active.
      Parameters:
      path - the path to the child (contained by the actual prefab). If null, the prefab itself (root object) will be affected.
      set - true to set the object active, false to disable it.

    • setLayer

      public void setLayer(String path, int layer, boolean recursively)
      Sets the layer of the prefab or a child of this prefab.
      Parameters:
      path - the path to the child (contained by the actual prefab). If null, the prefab itself (root object) will be affected.
      layer - the new layer you want to set.
      recursively - true to set the layer for all prefab childs (contained by the actual prefab), false to change it only for the specified element.

    • setLocalPosition

      public void setLocalPosition(String path, Vector3f position)
      Sets the position of the prefab or a child of this prefab, relative to its parent.
      Parameters:
      path - the path to the child (contained by the actual prefab). If null, the prefab itself (root object) will be affected.
      position - a vector which holds the new position coordinates.

    • setLocalRotation

      public void setLocalRotation(String path, Quaternion rotation)
      Sets the rotation of the prefab or a child of this prefab, relative to its parent.
      Parameters:
      path - the path to the child (contained by the actual prefab). If null, the prefab itself (root object) will be affected.
      rotation - the quaternion which represents the new rotation.

    • setLocalScale

      public void setLocalScale(String path, Vector3f scale)
      Sets the local scale of the prefab or a child of this prefab, relative to its parent.
      Parameters:
      path - the path to the child (contained by the actual prefab). If null, the prefab itself (root object) will be affected.
      scale - the new scale along the X, Y and Z axis.

    • readLocalPosition

      public void readLocalPosition(String path, Player player, Callback<Vector3f> callback)
      Reads the actual local position of the prefab (or a child of this prefab, specified by the path) from a particular player. This may differ from the position set by GameObject.setLocalPosition(net.risingworld.api.utils.Vector3f), because if the element has a Rididbody physics component or if it's affected by an Animator, the position may be modified on the clientside (and it may be different for each client). These changes are not reflected in the API.
      Once the result is available, the provided callback is invoked (containing the position of the element as Vector3f).
      Parameters:
      path - the path to the child (contained by the actual prefab). If null, the prefab itself (root object) is used.
      player - the player you want to read the information from. If null, the position is read from the first player this game object is currently linked to. If this game object is not linked with any players yet, an exception is thrown.
      callback - callback that is invoked once the result is available from the client.
      Example: Read local position of a child called "inner2", child of "inner", child of this prefab
      1prefab.readLocalPosition("inner/inner2", player, (pos) -> {
      2 System.out.println("Position of 'inner2': " + pos);
      3});

    • readWorldPosition

      public void readWorldPosition(String path, Player player, Callback<Vector3f> callback)
      Reads the actual world position of the prefab (or a child of this prefab, specified by the path) from a particular player. Once the result is available, the callback is invoked (containing the world position of the element as Vector3f).
      Parameters:
      path - the path to the child (contained by the actual prefab). If null, the prefab itself (root object) is used.
      player - the player you want to read the information from. If null, the position is read from the first player this game object is currently linked to. If this game object is not linked with any players yet, an exception is thrown.
      callback - callback that is invoked once the result is available from the client.

    • readLocalRotation

      public void readLocalRotation(String path, Player player, Callback<Quaternion> callback)
      Reads the actual local rotation of the prefab (or a child of this prefab, specified by the path) from a particular player. This may differ from the rotation set by GameObject.setLocalRotation(net.risingworld.api.utils.Quaternion), because if the element has a Rididbody physics component or if it's affected by an Animator, the rotation may be modified on the clientside (and it may be different for each client). These changes are not reflected in the API.
      Once the result is available, the provided callback is invoked (containing the rotation of the element as Quaternion).
      Parameters:
      path - the path to the child (contained by the actual prefab). If null, the prefab itself (root object) is used.
      player - the player you want to read the information from. If null, the rotation is read from the first player this game object is currently linked to. If this game object is not linked with any players yet, an exception is thrown.
      callback - callback that is invoked once the result is available from the client.

    • readWorldRotation

      public void readWorldRotation(String path, Player player, Callback<Quaternion> callback)
      Reads the actual world rotation of the prefab (or a child of this prefab, specified by the path) from a particular player. Once the result is available, the callback is invoked (containing the world rotation of the element as Quaternion).
      Parameters:
      path - the path to the child (contained by the actual prefab). If null, the prefab itself (root object) is used.
      player - the player you want to read the information from. If null, the rotation is read from the first player this game object is currently linked to. If this game object is not linked with any players yet, an exception is thrown.
      callback - callback that is invoked once the result is available from the client.

    • addComponent

      public void addComponent(String path, String component)
      Adds a new Unity component to the prefab or a child of this prefab. The component is created via reflection, determined by the type name.
      Parameters:
      path - the path to the child (contained by the actual prefab). If null, the prefab itself (root object) will be affected.
      component - the name/type of the component.
      Example: Add a Rigidbody component to a prefab
      1//Create a new prefab
      2Prefab prefab = new Prefab(PrefabAsset.loadFromFile("..."));
      3prefab.setLayer(Layer.ITEM);
      4prefab.setLocalPosition(player.getPosition());
      5
      6//Add a collider to the prefab (necessary for physics)
      7prefab.addCollider(new BoxCollider());
      8
      9//Add rigidbody component to main prefab (path null)
      10prefab.addComponent(null, "Rigidbody");
      11
      12//Add prefab to player world
      13player.addGameObject(prefab);

    • removeComponent

      public void removeComponent(String path, String component)
      Removes a Unity component from the prefab or a child of this prefab. The component type is determined by name (i.e the game will remove the first component of that type on the prefab or the child)
      Parameters:
      path - the path to the child (contained by the actual prefab). If null, the prefab itself (root object) will be affected.
      component - the name/type of the component.

    • setComponentEnabled

      public void setComponentEnabled(String path, String component, boolean enabled)
      Enables or disables a component. This only works for components which are derived from the Behaviour component! If the component is not derived from Behaviour, nothing happens
      Parameters:
      path - the path to the child (contained by the actual prefab). If null, the prefab itself (root object) will be affected.
      component - the name/type of the component.
      enabled - true to set the component enabled, false to disable it.

    • setComponentProperty

      public void setComponentProperty(String path, String component, String property, Object value)
      Sets a component property via reflection.
      Parameters:
      path - the path to the child (contained by the actual prefab). If null, the prefab itself (root object) will be affected.
      component - the name/type of the component.
      property - the name of the property.
      value - the value you want to assign to the property. Make sure to use the correct type!

    • invokeComponentMethod

      public void invokeComponentMethod(String path, String component, String method, Object... parameters)

    • setAnimatorParameter

      public void setAnimatorParameter(String path, String parameter, float value)
      Sets a float parameter on the animator controller component of the prefab or a child of this prefab.
      Parameters:
      path - the path to the child (contained by the actual prefab). If null, the prefab itself (root object) will be affected.
      parameter - the name of the parameter.
      value - the value you want to assign.

    • setAnimatorParameter

      public void setAnimatorParameter(String path, String parameter, int value)
      Sets an int parameter on the animator controller component of the prefab or a child of this prefab.
      Parameters:
      path - the path to the child (contained by the actual prefab). If null, the prefab itself (root object) will be affected.
      parameter - the name of the parameter.
      value - the value you want to assign.

    • setAnimatorParameter

      public void setAnimatorParameter(String path, String parameter, boolean value)
      Sets a boolean parameter on the animator controller component of the prefab or a child of this prefab.
      Parameters:
      path - the path to the child (contained by the actual prefab). If null, the prefab itself (root object) will be affected.
      parameter - the name of the parameter.
      value - the value you want to assign.

    • setAnimatorTrigger

      public void setAnimatorTrigger(String path, String trigger)
      Sets the value of the given trigger parameter on the animator controller component.
      Parameters:
      path - the path to the child (contained by the actual prefab). If null, the prefab itself (root object) will be affected.
      trigger - the name of the trigger/parameter.

    • resetAnimatorTrigger

      public void resetAnimatorTrigger(String path, String trigger)
      Resets (i.e unsets) the value of the given trigger parameter on the animator controller component.
      Parameters:
      path - the path to the child (contained by the actual prefab). If null, the prefab itself (root object) will be affected.
      trigger - the name of the trigger/parameter you want to reset.

    • startAnimatorPlayback

      public void startAnimatorPlayback(String path)

    • stopAnimatorPlayback

      public void stopAnimatorPlayback(String path)

    • playAnimatorState

      public void playAnimatorState(String path, String state, int layer, float normalizedTime)

    • rebindAnimator

      public void rebindAnimator(String path, boolean keepState)
      Rebinds all properties and mesh data with the animator controller. This is important if you change the hierarchy of the prefab (and want newly added childs to be affected by the animator).
      Parameters:
      path - the path to the child (contained by the actual prefab). If null, the prefab itself (root object) will be affected.
      keepState - true if you want to keep the current animator state, false to reset it (default behaviour).

    • setMaterial

      public void setMaterial(String path, MaterialAsset material)
      Assigns a new material to the prefab or a child of this prefab.
      Parameters:
      path - the path to the child (contained by the actual prefab). If null, the prefab itself (root object) will be affected.
      material - the material asset you want to assign.

    • setMaterialParameter

      public void setMaterialParameter(String path, String parameter, float value)
      Sets a material parameter.
      Parameters:
      path - the path to the child (contained by the actual prefab). If null, the prefab itself (root object) will be affected.
      parameter - the material parameter. In Unity, they typically begin with an underscore.
      value - the value you want to assign.

    • setMaterialParameter

      public void setMaterialParameter(String path, String parameter, boolean value)
      Sets a material parameter.
      Parameters:
      path - the path to the child (contained by the actual prefab). If null, the prefab itself (root object) will be affected.
      parameter - the material parameter. In Unity, they typically begin with an underscore.
      value - the value you want to assign.

    • setMaterialParameter

      public void setMaterialParameter(String path, String parameter, Vector2f value)
      Sets a material parameter.
      Parameters:
      path - the path to the child (contained by the actual prefab). If null, the prefab itself (root object) will be affected.
      parameter - the material parameter. In Unity, they typically begin with an underscore.
      value - the value you want to assign.

    • setMaterialParameter

      public void setMaterialParameter(String path, String parameter, Vector3f value)
      Sets a material parameter.
      Parameters:
      path - the path to the child (contained by the actual prefab). If null, the prefab itself (root object) will be affected.
      parameter - the material parameter. In Unity, they typically begin with an underscore.
      value - the value you want to assign.
      Example:
      1Prefab prefab = new Prefab(PrefabAsset.loadFromFile(...));
      2prefab.setMaterialParameter("child/anotherchild", "_PositionProperty", new Vector3f(0f, 10f, 0f));
      3prefab.setLocalPosition(player.getPosition());
      4player.addGameObject(prefab);

    • setMaterialParameter

      public void setMaterialParameter(String path, String parameter, Vector4f value)
      Sets a material parameter. You can also use this method to change a color parameter of a material.
      Parameters:
      path - the path to the child (contained by the actual prefab). If null, the prefab itself (root object) will be affected.
      parameter - the material parameter. In Unity, they typically begin with an underscore.
      value - the value you want to assign.
      Example:
      1Prefab prefab = new Prefab(PrefabAsset.loadFromFile(...));
      2prefab.setMaterialParameter("child/anotherchild", "_BaseColor", new Vector4f(1f, 0f, 0f, 1f)); // <- color red
      3prefab.setLocalPosition(player.getPosition());
      4player.addGameObject(prefab);

    • setMaterialParameter

      public void setMaterialParameter(String path, String parameter, TextureAsset texture)
      Sets a material parameter.
      Parameters:
      path - the path to the child (contained by the actual prefab). If null, the prefab itself (root object) will be affected.
      parameter - the material parameter. In Unity, they typically begin with an underscore.
      texture - the texture you want to assign.
      Example:
      1Prefab prefab = new Prefab(PrefabAsset.loadFromFile(...));
      2prefab.setMaterialParameter("child/anotherchild", "_BaseColorMap", TextureAsset.loadFromFile(...));
      3prefab.setLocalPosition(player.getPosition());
      4player.addGameObject(prefab);

    • clearMaterialPropertyBlock

      public void clearMaterialPropertyBlock(String path, int materialIndex)
      Removes a MaterialPropertyBlock from a Renderer component.
      Parameters:
      path - the path to the child (contained by the actual prefab). If null, the prefab itself (root object) will be affected.
      materialIndex - optional material index (if a renderer has multiple materials), or 0 by default.

    • setVFXParameter

      public void setVFXParameter(String path, String parameter, float value)

    • setVFXParameter

      public void setVFXParameter(String path, String parameter, int value)

    • setVFXParameter

      public void setVFXParameter(String path, String parameter, boolean value)

    • setVFXParameter

      public void setVFXParameter(String path, String parameter, Vector2f value)

    • setVFXParameter

      public void setVFXParameter(String path, String parameter, Vector3f value)

    • setVFXParameter

      public void setVFXParameter(String path, String parameter, Vector4f value)

    • setVFXPaused

      public void setVFXPaused(String path, boolean pause)

    • setVFXPlayRate

      public void setVFXPlayRate(String path, float rate)

    • playVFX

      public void playVFX(String path)

    • stopVFX

      public void stopVFX(String path)

    • reinitVFX

      public void reinitVFX(String path)