SaintsField

SaintsField is a Unity extension tool for enhancing inspector and data serialization.

Developed by: TylerTemp, 墨瞳

Unity: 2022.2 or higher

[!TIP] A better document with TOC & Search: saintsfield.comes.today

(Yes, the project name comes from, of course, Saints Row 2)

Getting Started

Highlights

1. Works on deep nested fields!
2. When a target is drawn by the old IMGUI drawer, it will be rendered correctly inside UI Toolkit.
3. Allow stack on many cases. Only attributes that modified the label itself, and the field itself can not be stacked. All other attributes can mostly be stacked.
4. Allow dynamic arguments in many cases
5. Directly serialize dictionary, interface, hashset and more
6. Easily group different fields with box

Installation

• Using Unity Asset Store

• Using OpenUPM

  openupm add today.comes.saintsfield
  

• Using git upm:

  add to Packages/manifest.json in your project

  {
      "dependencies": {
          "today.comes.saintsfield": "https://github.com/TylerTemp/SaintsField.git",
          // your other dependencies...
      }
  }
  

• Using git upm (Unity UI):

  1. Window - Package Manager
  2. Click + button, Add package from git URL
  3. Enter the following URL:

  https://github.com/TylerTemp/SaintsField.git
  

• Using a unitypackage:

  Go to the Release Page to download a desired version of unitypackage and import it to your project

• Using a git submodule:

  git submodule add https://github.com/TylerTemp/SaintsField.git Packages/today.comes.saintsfield
  

If you have DOTween installed

• Please also ensure you do: Tools - Demigaint - DOTween Utility Panel, click Create ASMDEF
• Or disable related functions with Window - Saints - Disable DOTween Support
• If you can not find this menu, please read the "Add a Macro" section about how to manually disable DOTween support in SaintsField.

[Optional] To use the full functions of this project, please also do: Window - Saints - Enable SaintsEditor. Note this will break your existing Editor plugin like OdinInspector, NaughtyAttributes, MyToolbox, Tri-Inspector.

If you're using unitypackage or git submodule, but you put this project under another folder rather than Assets/SaintsField, please also do the following:

• Create Assets/Editor Default Resources/SaintsField.
• Copy files from the project's Editor/Editor Default Resources/SaintsField into your project's Assets/Editor Default Resources/SaintsField. If you're using a file browser instead of Unity's project tab to copy files, you may want to exclude the .meta file to avoid GUID conflict.

Troubleshoot

After installation, you can use Window - Saints - Troubleshoot to check if some attributes do not work.

namespace: SaintsField

Change Log

5.12.1

1. Fix: context menu in old unity did not show correctly, context menu for SaintsArray/SaintsList did not show
2. Fix: new gameobjects being spawned whenever a property is reset @peterdwdawe, PR#371
3. Add: ResizableTextArea support ShowInInspector and Button
4. Fix: reset context menu shows uppercase if a variable name starts with _, remove the k__BackingField information.

Note: all Handle attributes (draw stuff in the scene view) are in stage 1, which means the arguments might change in the future.

See the full change log.

General Attributes

Label & Text

LabelText

[!IMPORTANT] Enable SaintsEditor before using

Change the label text of a field. (To change element label of an array/list, use FieldLabelText instead.)

Parameters:

• string richTextXml the rich text xml for the label. Supported tag:

  • All Unity rich label tag, like <color=#ff0000>red</color>
  • <icon=path/to/image.png /> for icon
  • <label /> for current field name
  • <field />, <field.subField/>, <field.subField=formatControl /> read the value from the field first, if tag has sub-field, continue to read, then use string.Format if there is a formatControl. See the example below.
  • <container.Type /> for the class/struct name of the container of the field
  • <container.Type.BaseType /> for the class/struct name of the field's container's parent
  • <index />, <index=formatControl /> for the index if the target is an array/list

  Note about format control:

  • If the format contains {}, it will be used like a string.Format. E.g. <field.subField=(--<color=red>{0}</color>--)/> will be interpreted like string.Format("(--<color=red>{0}</color>--)", this.subField).
  • Otherwise, it will be rewritten to {0:formatControl}. E.g., <index=D4/> will be interpreted like string.Format("{0:D4}", index).

  null means no label

  for icon, it will search the following path:

  • "Assets/Editor Default Resources/SaintsField/" (You can override things here)
  • "Assets/SaintsField/Editor/Editor Default Resources/SaintsField/" (this is most likely to be when installed using unitypackage)
  • "Packages/today.comes.saintsfield/Editor/Editor Default Resources/SaintsField/" (this is most likely to be when installed using upm)
  • Assets/Editor Default Resources/, then fallback to built-in editor resources by name (using EditorGUIUtility.Load)

  You can also use Unity Editor's built-in icons. See UnityEditorIcons. e.g. <icon=d_AudioListener Icon/>

  for color, you can use Window - Saints - EColor Preview to view all the pre-set colors. It supports:

  • Standard Unity Rich Label colors:

    aqua, black, blue, brown, cyan, darkblue, fuchsia, green, gray, grey, lightblue, lime, magenta, maroon, navy, olive, orange, purple, red, silver, teal, white, yellow

  • Standard Unity Pre-Set Color Presets (Unity 6.2 as a reference), e.g. darkViolet, hotPink

  • Some extra colors from NaughtyAttributes & UI Toolkit:

    clear, pink, indigo, violet, charcoalGray, oceanicSlate

  • html color which is supported by ColorUtility.TryParseHtmlString, like #RRGGBB, #RRGGBBAA, #RGB, #RGBA

  

  If it starts with $, the leading $ will be removed and isCallback will be set to true. Use \$ to escape the starting $.

• bool isCallback=false (Depreacted, use $ with "richTextXml" instead)

  if it's a callback (a method/property/field)

// Please ensure you already have SaintsEditor enabled in your project before trying this example
using SaintsField.Playa;

[LabelText("<color=lime>It's Labeled!")]
public List<string> myList;

[LabelText("$" + nameof(MethodLabel))]
public string[] myArray;

private string MethodLabel(string[] values)
{
    return $"<color=green><label /> {string.Join("", values.Select(_ => "<icon=star.png />"))}";
}

Example of using <field /> to display field value/propery value:

using SaintsField;

public class SubField : MonoBehaviour
{
    [SerializeField] private string _subLabel;

    public double doubleVal;
}

[Separator("Field")]
// read field value
[LabelText("<color=lime><field/>")] public string fieldLabel;
// read the `_subLabel` field/function from the field
[LabelText("<field._subLabel/>"), GetComponentInChildren, Expandable] public SubField subField;
// again read the property
[LabelText("<color=lime><fie