PropertyRefs

PropertyRefs is an open source tool for Unity, crafted to streamline your game development tasks. By creating references to the properties of the components, you can efficiently access and manipulate them from other scripts, centralizing meaningful properties of a game object, prefab, or a scene in one location. This is a significant advantage for game and level designers, offering an enhanced and seamless workflow.

Features

Access from Editor

With a custom property drawer, PropertyRefs provides an intuitive interface for gathering all significant properties in one place. This not only eliminates the tedious search through countless properties but also promotes a cleaner, more organized codebase.

Access from Code

Developers have the flexibility to modify the values of the PropertyRefs programmatically. For more information on how to access and modify properties programmatically, please refer to the Property Access Methods section.

AOT Systems Support

PropertyRefs is equipped with a dual-mode functionality. Initially, it uses System Reflection to access the values of component properties. However, for AOT systems, where System Reflection is not applicable, PropertyRefs seamlessly switches to a Roslyn Source Generator. For more details on how AOT systems are supported, please see the AOT Systems Support and Code Generation section.

Requirements

The PropertyRefs package is currently supported on Unity 2021.3.17f1. Usage in other versions of Unity may result in unexpected behavior. Please ensure your Unity environment meets this requirement before installation to guarantee the package's optimal functionality.

Installation

There are several methods available to install PropertyRefs into your Unity project. Choose the one that best suits your needs. It's recommended to install via npm if you wish to keep the package up-to-date easily, as future releases and updates will be readily available.

• Package Name:

  games.javier.upm.propertyrefs
  

• Display Package Name:

  Javier Games
  

• NPM Registry URL:

  https://registry.npmjs.org
  

• Scope(s):

  games.javier
  

• OpenUPM CI command

  openupm add games.javier.upm.propertyrefs
  

This package is being distributed on npm, OpenUPM or a downloadable Tarball from the Releases section of this repository or from the dedicated itch.io page. For detailed installation instructions, please refer to the guide on our installation documentation page.

Usage

PropertyRefs is designed with an intuitive interface to ensure a seamless and user-friendly experience. To use PropertyRefs in your projects, follow the general usage instructions below:

General Usage

To establish a reference to the properties of your components, declare a private SerializedProperty or a public field of PropertyRef type in a custom class. Once declared, the Inspector will allow you to select the component and the property for the reference.

using System.Collections.Generic;
using UnityEngine;
using JG.UPM.PropertyRefs;

public class PrefabProperties : MonoBehaviour
{
   [SerializeField]
   private PropertyRef myPropertyRef;
   
   [SerializeField]
   private List<PropertyRef> myListOfProperties;
}

You can also declare a list of PropertyRef instances. In this mode, PropertyRefs conveniently labels the properties in the list with the name of the game object and the property. This labeling facilitates easier identification of properties.

Property Access Methods

To ensure that a newly created component's properties are identifiable by PropertyRefs, the properties must be declared with read and write access. If a property lacks read and write access, PropertyRefs won't be able to identify it.

using UnityEngine;

public class CustomComponent : MonoBehaviour
{
    public float MyFindableProperty { get; set; }
}

Moreover, PropertyRefs enables you to modify and obtain the value of the PropertyRef programmatically. However, caution is advised as this option doesn't recommend the assignment of values that are of a different type to the PropertyRef. If such an assignment occurs, the value of the PropertyRef will remain unchanged.

using UnityEngine;
using JG.UPM.PropertyRefs;

public class EditableProperty : MonoBehaviour
{
    [SerializeField]
    private PropertyRef myEditablePropertyRef;

    private void Start()
    {
        var value = (float) myEditablePropertyRef.GetValue();
        Debug.Log($"My value is {value}");

        value += 5;
        myEditablePropertyRef.SetValue(value);
        Debug.Log($"My new value is {value}");
    }
}

AOT Systems Support and Code Generation

PropertyRefs includes a built-in Roslyn source generator for supporting Ahead-Of-Time (AOT) systems, like iOS. To activate this feature, locate a Registry.PropertyRefsSourceGenerator.additionalfile file somewhere in your project. This file serves as a registry for the properties you can use.

When a component or a property that isn't registered is assigned to a PropertyRef, it will display an option for you to register them. This ensures that your AOT system is fully supported and that your property references are generated correctly. The JSON file below is a sample of how the registry is conformed.

{
   "components": [
      {
         "type": "UnityEngine.Transform", 
         "properties": [
            {
               "name": "position", 
               "type": "UnityEngine.Vector3"
            }
         ]
      }
   ]
}

With these features and flexible options, PropertyRefs aims to enhance your Unity development experience, offering an enhanced and seamless workflow.

License

PropertyRefs is available under the MIT license. See the LICENSE file for more info.

Contribution

Please read our Contributing Guide before submitting a Pull Request to the project.

Support

For any questions or issues, please open a new issue on this repository.

Acknowledgements

We would like to express our gratitude to Kenney for providing the assets used to create the samples and images in this repository. These models are under the Creative Commons Zero (CC0) license.