Ni-Essentials

Ni-Essentials is a foundational module that provides a collection of basic utilities and functions commonly used across various projects. It serves as a generic toolkit to streamline development and maintain consistency across different modules and applications.

⚠️ Documentation is incomplete. For detailed information, please refer to the code and XML comments.

Requirements

• Unity 2022.2 or later
• Text Mesh Pro 3.0.6 or later

Installation

Manual

1. Clone this repository or download the source files.
2. Copy the Ni-Essentials folder into your Unity project's Assets directory.

UPM

1. Open Package Manager from Window > Package Manager.
2. Click the "+" button > Add package from git URL.
3. Enter the following URL:

https://github.com/HoSHIZA/Ni-Essentials.git

Manual with manifest.json

1. Open manifest.json.
2. Add the following line to the file:

"com.ni-games.essentials" : "https://github.com/HoSHIZA/Ni-Essentials.git"

Attributes

Misc

[InfoBox]: Adds a HelpBox above the field.

[InfoBox("Message", MessageType.Info)] public int a;

---

[ReadOnly]: Makes fields read-only in the inspector.

[ReadOnly] public int a;

---

Decorators

[Reference]: Displays a field for selecting managed references.

Displays a field for selecting a managed reference in the inspector. When used, you must mark the desired classes with the [System.Serializable] attribute.

Works only when paired with [SerializeReference].

public interface IManagedObject {}
public interface ISomeManagedObject {}

[Serializable]
public class A : IManagedObject {}

[Category("Category")] // Specifies the category in the selection menu.
[DisplayName("New Name")] // Renames the class in the selection menu.
[Serializable]
public class B : IManagedObject {}

[Category("")] // Removes from all categories, including the inheritance tree.
[Serializable]
public class C : IManagedObject {}

[Serializable]
public class D : ISomeManagedObject {}

[Reference]
public IManagedObject ManagedReferenceField;

// Shows only objects inherited from `ISomeManagedObject` for selection.
[Reference(typeof(ISomeManagedObject))]
public IManagedObject ManagedReferenceField;

---

[ScenePicker]: Creates a dropdown for selecting scenes.

Applies only to a field of type string and returns the name of the scene.

[ScenePicker] public string SceneName;

---

[TypePicker]: Creates a dropdown for selecting Types.

Applies only to a field of type string and returns AssemblyQualified type name.

[TypePicker] public string TypeName;

---

[ObjectPicker]: Creates a dropdown for selecting UnityEngine.Objects.

⚠️ May break inspector

[ObjectPicker] public Object UnityObject;

Styling

[Title]: Adds a title with a separator line.

[Title("Header Text", LabelColor = "red", LineColor = "green")]
public string a;

---

[HideLabel]: Hides the label.

[HideLabel] public string a;

---

[LabelText]: Sets a custom label.

[LabelText("New Label")] public string a;

---

Components

MonoBehaviour

• Destroyer: Destroys the object when it is created.
• Disabler: Disables the object when it is created.
• DontDestroyOnLoad: Marks the object for DontDestroyOnLoad.

UI

AnchorSnap: Dynamic anchoring.

NonDrawingGraphic: MaskableGraphic designed for raycast.

DraggableRect: Draggable Rect.

Collections

FastList: High-performance, minimal array-based list.

FastList<string> list = new FastList<string>(32);

Helpers

PlayerLoopHelper: Modify Unity PlayerLoop and access callbacks.

It allows you to add your own runners, and also provides access to PlayerLoop callbacks for each timing via static Action.

using NiGames.Essentianls.Helpers;

public struct CustomUpdate { } // Update
public struct CustomFixedUpdate { } // FixedUpdate

// Method to modify PlayerLoop, use it to modify PlayerLoop conveniently.
// Automatically applies PlayerLoop changes when the method completes.
PlayerLoopHelper.ModifyLoop(systems =>
{
    // Inserts a custom runner into the Loop of the specified timing.
    systems.InsertLoop<Update, CustomUpdate>(static () => { /* Action */ });
    
    // Inserts a custom runner into the Loop of the specified timing.
    systems.InsertLoop<FixedUpdate, CustomFixedUpdate>(static () => { /* Action */ });
    
    // Attempt to remove the runner.
    systems.TryRemoveLoop<FixedUpdate, CustomFixedUpdate>();
});

It is also possible to subscribe to events from PlayerLoop.

PlayerLoopHelper.OnFixedUpdate += static () => { /* Action */ };

or...

PlayerLoopHelper.Subscribe(PlayerLoopTiming.EarlyUpdate, static () => { /* Action */ });

---

ScreenHelper: Track screen resolution and orientation changes.

using NiGames.Essentianls.Helpers;

var isLandscape = ScreenHelper.IsLandscape;
var isPortrait = ScreenHelper.IsPortrait;

ScreenHelper.ResolutionChanged += newResolution => { /* Action */ };
ScreenHelper.OrientationChanged += newOrientation => { /* Action */ };

ScreenHelper.SetPollingTime(2f); // Sets the polling time (in seconds). If 0, each frame is polled.

---

InitHelper: Safe initialization with disabled domain reloading.

using NiGames.Essentianls.Helpers;

var isLandscape = ScreenHelper.IsLandscape;
var isPortrait = ScreenHelper.IsPortrait;

ScreenHelper.ResolutionChanged += newResolution => { /* Action */ };
ScreenHelper.OrientationChanged += newOrientation => { /* Action */ };

ScreenHelper.SetPollingTime(2f); // Sets the polling time (in seconds). If 0, each frame is polled.

Features

Easing

Easing: Built-in easing functions and utility class.

using NiPrefs.Essentianls.Easing;

float t = 0.5f;
float easedT = EaseUtility.Evaluate(t, Ease.InCubic); 
float easedT = EaseUtility.Evaluate(t, Ease.InOutBounce);

Func<float, float> easeFunc = EaseFunction.Linear;

---

UI

UI Blocker: Create UI blockers to prevent event propagation.

// TODO

---

Pooling

AbstractPooledBuffer: Used to implement the Builder pattern.

Example Buffer implementation:

public class SomeBuilderBuffer : AbstractPooledBuffer<SomeBuilderBuffer> 
{
    public bool Parameter1;
    public string Parameter2;
    
    protected override void Reset()
    {
        Parameter1 = false;
        Parameter2 = "default";
    }
}

Example Builder implementation:

public struct SomeBuilder
{
    internal ushort Revision;
    internal SomeBuilderBuffer Buffer;
    
    internal SomeBuilder(SomeBuilderBuffer buffer)
    {
        Revision = buffer.Revision;
        Buffer = buffer;
    }

    public readonly SomeBuilder WithParameter1(bool value)
    {
        Buffer.Parameter1 = value;
        return this;
    }

    public readonly SomeBuilder WithParameter2(string value)
    {
        Buffer.Parameter2 = value;
        return this;
    }
    
    public SomeObject Build() 
    {
        var result = new SomeObject(Buffer.Parameter1, Buffer.Parameter2);
        
        Buffer.Dispose();
        
        return result;
    }
}

Usage:

SomeBuilderBuffer buffer = SomeBuilderBuffer.GetPooled();
SomeBuilder builder = new SomeBuilder(buffer);

builder.WithParameter1(true);

SomeObject result = builder.Build();

---

Other

Impl<TInterface>: Allows you to reference objects with the specified interface in the inspector.

// TODO

Utility

• AssetDatabaseUtility: Extended AssetDatabase capabilities.
• ComplexConvert: Additional complex type conversion methods.

Unsafe

• ManagedPtr: Type for safely retrieve pointers to managed objects.
• NiUnsafe: Wrapper for memory manipulation functions.
• NiUnsafeExtensions: Simplify IntPtr operations.

Known Bugs

• Inspector breaks in some scenarios using ObjectPickerField.

License

This project is licensed under the MIT License.