Getting Started with Unity Helpers¶

This guide introduces key features that can help reduce repetitive coding patterns.

Unity Helpers is a toolkit used in commercial games that reduces common boilerplate patterns in Unity development. This guide covers the top features and basic usage patterns, whether you're a beginner or a senior engineer.

Core Features¶

Three core principles:

1. 🎯 Reduced Boilerplate¶

Common APIs:

• Random selection with weights? → random.NextWeightedIndex(weights)
• Auto-wire components? → [SiblingComponent] private Animator animator;
• Gaussian distribution? Perlin noise? → Built-in, one method call

Self-documenting code:

1
2
3

[SiblingComponent] private Animator animator;                      // Clear intent
[ParentComponent(OnlyAncestors = true)] private Rigidbody2D rb;  // Explicit search
[ChildComponent(MaxDepth = 1)] private Collider2D[] colliders;   // Limited scope

Error messages:

• Missing components? → Full GameObject path + component type
• Invalid queries? → Explanation of what went wrong + how to fix it
• Schema issues? → Specific guidance for your serialization problem

2. ⚡ Performance Characteristics¶

Speed improvements measured in benchmarks:

• 10-15x faster in benchmarks random generation (benchmark details)
• 10-100x faster in benchmarks reflection (varies by operation; see benchmark details)
• O(log n) spatial queries tested with millions of objects (benchmark details)
• Zero GC with buffering pattern

Benchmark Results:

• Stable 60 FPS with 1000+ AI agents (benchmark details)
• No allocation spikes from pooled collections
• Deterministic replays with seedable RNG

3. ✅ Testing & Compatibility¶

• ✅ 8,000+ automated tests - Edge cases are handled through test coverage
• ✅ Shipped in commercial games - Used at scale in production
• ✅ IL2CPP/WebGL compatible - Works with aggressive compilers
• ✅ Schema evolution - Player saves maintain compatibility across updates
• ✅ SINGLE_THREADED optimized - Reduced overhead on WebGL

Key capabilities:

• Edge cases are handled through test coverage
• Consistent behavior in editor and builds
• Player data compatibility maintained across updates

Choose Your Path¶

🎯 Path 1: "I Have a Specific Problem"¶

Jump directly to the solution you need:

Performance Issues?

• Slow random number generation → Random Generators
• Too many objects to search → Spatial Queries
• Frame drops from allocations → Buffering Pattern

Workflow Issues?

• Writing too much GetComponent → Auto Component Wiring
• Manual sprite animation setup → Editor Tools
• Prefab validation problems → Prefab Checker

Architecture Issues?

• Need global settings → Singletons
• Need buff/debuff system → Effects System
• Need save/load system → Serialization
• Migrating from Odin Inspector → Odin Migration Guide

📚 Path 2: "I Want to Understand the Full Picture"¶

Full documentation overview (best for team leads and senior developers):

1. Read Main Documentation - Full feature overview
2. Review Features Documentation - Detailed API documentation
3. Explore category-specific guides as needed

💡 Path 3: "I Learn Best from Examples"¶

See it working first, understand the theory later:

1. Follow the 3 Quick Examples below
2. Explore the Samples~ folder (see sample README files in the repo) for DI integration examples
3. Modify examples for your specific needs
4. Read the detailed guides when you need to go deeper

Installation¶

See the Installation section in the main README for detailed installation instructions using:

• OpenUPM (Recommended) — Easy version management via Package Manager or CLI
• Git URL — Direct from GitHub, great for CI/CD pipelines
• NPM Registry — For teams already using NPM scoped registries
• Source — Import .unitypackage from releases, or clone the repository

After installation, verify the package appears in Window → Package Manager under "My Registries" or "In Project".

Three Quick Examples¶

Example 1: Random Generation (Beginner)¶

Problem: Unity's UnityEngine.Random is slow and not seedable.

Solution:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

using WallstopStudios.UnityHelpers.Core.Random;
using WallstopStudios.UnityHelpers.Core.Extension;

public class LootDrop : MonoBehaviour
{
    void Start()
    {
        // Performance comparison available in benchmarks
        IRandom rng = PRNG.Instance;

        // Basic usage
        int damage = rng.Next(10, 20);
        float chance = rng.NextFloat();

        // Weighted random selection
        string[] loot = { "Common", "Rare", "Epic", "Legendary" };
        float[] weights = { 0.6f, 0.25f, 0.10f, 0.05f };
        int index = rng.NextWeightedIndex(weights);
        Debug.Log($"Dropped: {loot[index]}");
    }
}

⚠️ Common Mistake: Don't use UnityEngine.Random and PRNG.Instance together in the same class - pick one and stick with it for consistent results.

Learn More: Random Performance

Example 2: Component Wiring (Beginner)¶

Problem: Writing GetComponent calls everywhere is tedious and error-prone.

Solution:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

using UnityEngine;
using WallstopStudios.UnityHelpers.Core.Attributes;

public class Player : MonoBehaviour
{
    // Auto-finds SpriteRenderer on same GameObject
    [SiblingComponent]
    private SpriteRenderer spriteRenderer;

    // Auto-finds Rigidbody2D in parent hierarchy
    [ParentComponent]
    private Rigidbody2D rigidbody;

    // Auto-finds all Collider2D in immediate children only
    [ChildComponent(OnlyDescendants = true, MaxDepth = 1)]
    private Collider2D[] childColliders;

    void Awake()
    {
        // One call wires all attributed components
        this.AssignRelationalComponents();

        // Now use them
        spriteRenderer.color = Color.red;
        rigidbody.velocity = Vector2.up * 5f;
        Debug.Log($"Found {childColliders.Length} child colliders");
    }
}

⚠️ Common Mistake: Don't call AssignRelationalComponents() in Update() - it should only run once during initialization (Awake/Start).

Learn More: Relational Components

Using With DI Containers (VContainer/Zenject/Reflex)¶

• If you use dependency injection, you can auto-populate relational fields right after DI injection.
• Quick setup:
• VContainer: in LifetimeScope.Configure, call builder.RegisterRelationalComponents().
• Zenject/Extenject: add RelationalComponentsInstaller to your SceneContext and (optionally) enable the scene scan on initialize.
• Reflex: attach RelationalComponentsInstaller alongside your SceneScope. The installer binds the assigner, hydrates the active scene, and can listen for additive scenes. Use ContainerRelationalExtensions helpers (InjectWithRelations, InstantiateGameObjectWithRelations, etc.) when spawning objects through the container.
• Samples: See sample folders in the repository for VContainer, Zenject, and Reflex integration examples
• Full guide with scenarios and testing tips: Dependency Injection Integrations

Example 3: Spatial Queries (Intermediate)¶

Problem: Finding nearby objects with FindObjectsOfType and distance checks is O(n) and slow.

Solution:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

using WallstopStudios.UnityHelpers.Core.DataStructure;
using UnityEngine;
using System.Collections.Generic;

public class EnemyManager : MonoBehaviour
{
    private QuadTree2D<Enemy> enemyTree;
    private List<Enemy> nearbyBuffer = new(64); // Reusable buffer

    void Start()
    {
        // Build tree once (O(n log n))
        Enemy[] enemies = FindObjectsOfType<Enemy>();
        enemyTree = new QuadTree2D<Enemy>(enemies, e => e.transform.position);
    }

    public List<Enemy> GetEnemiesNearPlayer(Vector2 playerPos, float radius)
    {
        nearbyBuffer.Clear();

        // Fast query: O(log n) instead of O(n)
        enemyTree.GetElementsInRange(playerPos, radius, nearbyBuffer);

        return nearbyBuffer;
    }
}

⚠️ Common Mistake: Spatial trees are immutable - you must rebuild the tree when enemy positions change. For frequently moving objects, use SpatialHash2D instead.

Learn More:

• 2D Spatial Trees Guide
• Performance Benchmarks

What Should I Learn Next?¶

Based on your needs:

For Gameplay Programmers¶

1. Master the Effects System - Data-driven buffs/debuffs
2. Start: Effects System TL;DR

3. Why: Build status effects without writing repetitive code

4. Use Spatial Trees for AI - Efficient awareness systems

5. Start: Spatial Trees 2D Guide

6. Why: Make enemy AI scale to hundreds of units

7. Learn Serialization - Save systems and networking

8. Start: Serialization Guide
9. Why: Save/load with Unity types supported

For Tools/Editor Programmers¶

1. Explore Editor Tools - Automate your asset pipeline
2. Start: Editor Tools Guide

3. Why: 20+ tools for sprites, animations, validation, and more

4. Use ScriptableObject Singletons - Global settings management

5. Start: Singletons Guide

6. Why: Auto-created, Odin-compatible config assets

7. Master Property Drawers - Better inspector workflows

8. Start: Property Drawers
9. Why: Conditional fields, dropdowns, validation

For Performance-Focused Developers¶

1. Study Data Structures - Choose the right container
2. Start: Data Structures Guide

3. Why: Heaps, tries, sparse sets, and more with clear trade-offs

4. Use Math Helpers - Avoid common pitfalls

5. Start: Math & Extensions

6. Why: Modulo, geometry, color averaging, and more

7. Adopt the Buffering Pattern - Zero-allocation queries

8. Start: Buffering Pattern
9. Why: Stable GC even under load

Common Questions¶

"Is this production-ready?"¶

Yes! Unity Helpers is:

• ✅ Used in shipped commercial games
• ✅ 8,000+ automated test cases
• ✅ Compatible with Unity 2022, 2023, and Unity 6
• ✅ Zero external dependencies — protobuf-net is bundled
• ✅ Fully WebGL/IL2CPP compatible with optimized SINGLE_THREADED hot paths
• ✅ Multiplatform support - Desktop, Mobile, Web, and Consoles
• ⚠️ Requires .NET Standard 2.1

"Will this conflict with my existing code?"¶

No! Unity Helpers:

• ✅ Uses namespaces (WallstopStudios.UnityHelpers.*)
• ✅ Doesn't modify Unity types or global state
• ✅ Opt-in design - use what you need

"How do I get help?"¶

1. Check the Troubleshooting section in the relevant guide
2. Search the GitHub Issues
3. Open a new issue with code examples and error messages

"Can I use this in commercial projects?"¶

Yes! Unity Helpers is released under the MIT License - use it freely in commercial projects.

Next Steps¶

Pick one feature that solves your immediate problem:

Ready to dive deeper? Return to the main README for the complete feature list.

Building something cool? We'd love to hear about it! Share your experience by opening an issue.

📚 Related Documentation¶

Core Guides:

• Main README - Complete feature overview
• Feature Index - Alphabetical reference
• Glossary - Term definitions
• Odin Migration Guide - Migrate from Odin Inspector

Deep Dives:

• Relational Components - Auto-wiring guide
• Effects System - Buff/debuff system
• Spatial Trees 2D - Fast spatial queries
• Serialization - Save systems and networking
• Editor Tools - Asset pipeline automation

DI Integration:

• VContainer Sample - VContainer integration guide (see Samples~ folder in repo)
• Zenject Sample - Zenject integration guide (see Samples~ folder in repo)

Need help? Open an issue or check Troubleshooting