Utilities tested in commercial releases
Unity Helpers reduces repetitive work with utilities tested in commercial releases. Benchmarks demonstrate 10-15x faster random generation compared to Unity.Random and significant speedups for common reflection operations. From auto-wiring components to fast spatial queries, this toolkit provides common utilities for Unity development.
"},{"location":"#quick-install","title":"Quick Install","text":"OpenUPM (Recommended)Git URLNPM RegistrySource Bashopenupm add com.wallstop-studios.unity-helpers\nIn Unity Package Manager, click Add package from git URL and enter:
Text Onlyhttps://github.com/wallstop/unity-helpers.git\nAdd scoped registry in manifest.json:
{\n \"scopedRegistries\": [\n {\n \"name\": \"npm\",\n \"url\": \"https://registry.npmjs.org\",\n \"scopes\": [\"com.wallstop-studios\"]\n }\n ],\n \"dependencies\": {\n \"com.wallstop-studios.unity-helpers\": \"3.0.0\"\n }\n}\nDownload the latest release .unitypackage or clone the repository.
Grouping, buttons, conditional display, toggle grids for Unity inspectors, free and open source.
Learn more
"},{"location":"#10-15x-faster-random","title":"10-15x Faster Random","text":"PRNG.Instance provides high-performance random generation with API including weighted selection, Gaussian distribution, and Perlin noise.
Learn more
"},{"location":"#zero-boilerplate-component-wiring","title":"Zero-Boilerplate Component Wiring","text":"Auto-wire components with attributes like [SiblingComponent], [ParentComponent], and [ChildComponent]. Works with DI containers.
Learn more
"},{"location":"#data-driven-effects-system","title":"Data-Driven Effects System","text":"Designer-friendly buffs and debuffs as ScriptableObjects. Add new effects via data instead of code changes.
Learn more
"},{"location":"#olog-n-spatial-queries","title":"O(log n) Spatial Queries","text":"QuadTree, KdTree, RTree, OctTree, and SpatialHash for 2D and 3D. Efficient spatial queries without linear iteration.
Learn more
"},{"location":"#20-editor-tools","title":"20+ Editor Tools","text":"Automate sprite, animation, texture, and prefab workflows. Reduces manual repetitive tasks.
Learn more
"},{"location":"#first-time-here","title":"First Time Here?","text":"Pick your starting point based on your biggest pain point:
Your Problem Your Solution Time to Value Writing custom editors Inspector Tooling - Inspector attributes, free ~2 minutes WritingGetComponent everywhere Relational Components - Auto-wire with attributes ~2 minutes Need buffs/debuffs system Effects System - Designer-friendly ScriptableObjects ~5 minutes Slow spatial searches Spatial Trees - O(log n) queries ~5 minutes Random is too slow/limited Random Generators - 10-15x faster with weighted selection, Gaussian, Perlin noise ~1 minute Need save/load system Serialization - Unity types supported ~10 minutes Manual sprite workflows Editor Tools - 20+ automation tools ~3 minutes Not sure where to start?
The Getting Started Guide walks through the top 3 features in 5 minutes.
"},{"location":"#quick-examples","title":"Quick Examples","text":""},{"location":"#auto-wire-components","title":"Auto-Wire Components","text":"Player.csusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class Player : MonoBehaviour\n{\n // Auto-finds on same GameObject\n [SiblingComponent] private SpriteRenderer spriteRenderer;\n\n // Auto-finds in parent hierarchy\n [ParentComponent] private Rigidbody2D rigidbody;\n\n // Auto-finds all in children\n [ChildComponent] private Collider2D[] childColliders;\n\n void Awake()\n {\n this.AssignRelationalComponents(); // One call wires all marked fields\n }\n}\nusing WallstopStudios.UnityHelpers.Core.Random;\nusing WallstopStudios.UnityHelpers.Core.Extension;\n\npublic class LootDrop : MonoBehaviour\n{\n void Start()\n {\n // 10-15x faster than UnityEngine.Random\n IRandom rng = PRNG.Instance;\n\n // Basic usage\n int damage = rng.Next(10, 20);\n float chance = rng.NextFloat();\n\n // Weighted random selection\n string[] loot = { \"Common\", \"Rare\", \"Epic\", \"Legendary\" };\n float[] weights = { 0.6f, 0.25f, 0.10f, 0.05f };\n int index = rng.NextWeightedIndex(weights);\n Debug.Log($\"Dropped: {loot[index]}\");\n }\n}\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class CharacterStats : MonoBehaviour\n{\n [WGroup(\"combat\", \"Combat Stats\", collapsible: true)]\n public float maxHealth = 100f;\n [WGroupEnd(\"combat\")]\n public float defense = 10f;\n\n public enum WeaponType { Melee, Ranged, Magic }\n public WeaponType weaponType;\n\n [WShowIf(nameof(weaponType), WShowIfComparison.Equal, WeaponType.Ranged)]\n public int ammoCapacity = 30;\n\n [WButton(\"Heal to Full\", groupName: \"Debug\")]\n private void HealToFull() { maxHealth = 100f; }\n}\n8,000+ automated tests.
"},{"location":"#shipped-in-commercial-games","title":"Shipped in Commercial Games","text":"Used in commercial game releases.
"},{"location":"#il2cpp-webgl-compatible","title":"IL2CPP & WebGL Compatible","text":"Compatible with IL2CPP and WebGL. Includes optimizations for AOT compilation.
"},{"location":"#schema-evolution","title":"Schema Evolution","text":"Forward and backward compatible serialization \u2014 add new fields without breaking existing saves.
"},{"location":"#documentation","title":"Documentation","text":"Unity Helpers is released under the MIT License. Use it freely in commercial and personal projects.
Ready to get started?
Getting Started Guide View on GitHub
"},{"location":"404/","title":"Page Not Found","text":"The page you're looking for doesn't exist or has been moved.
"},{"location":"404/#what-can-you-do","title":"What can you do?","text":"If you believe this is an error, please open an issue.
"},{"location":"readme/","title":"Unity Helpers","text":"\ud83e\udd16 AI Assistance Disclosure:
Recent versions of this project have utilized AI assistance for feature development, bug detection, performance optimization, and documentation.
The original codebase was developed entirely by humans over several years.
Reduces boilerplate code for common Unity patterns.
Unity Helpers reduces repetitive work with tested utilities. Benchmarks show 10-15x faster random generation than Unity.Random and significant speedups for common reflection operations (see performance docs). From auto-wiring components to efficient spatial queries, this toolkit provides tools for Unity development.
"},{"location":"readme/#quick-install","title":"\ud83d\udce6 Quick Install","text":"Source Install Method OpenUPM (Recommended)openupm add com.wallstop-studios.unity-helpers Git URL Package Manager \u2192 Add from git URL \u2192 https://github.com/wallstop/unity-helpers.git NPM Add scoped registry https://registry.npmjs.org \u2192 search com.wallstop-studios.unity-helpers Source Import .unitypackage or clone repo \ud83d\udc49 Full installation instructions with step-by-step guides for each method.
Key Features:
\ud83d\uddfa\ufe0f Roadmap Snapshot \u2014 See the Roadmap for prioritized details.
\ud83d\udcda New to Unity Helpers? Start here: Getting Started Guide
\ud83d\udd0d Looking for something specific? Check the Feature Index
\u2753 Need a definition? See the Glossary
"},{"location":"readme/#first-time-here","title":"\ud83d\udc4b First Time Here?","text":"Choose your starting point:
Your Problem Your Solution Time to Value \ud83c\udfa8 Writing custom editors Inspector Tooling - Odin-level features, free ~2 minutes \ud83d\udc0c WritingGetComponent everywhere Relational Components - Auto-wire with attributes ~2 minutes \ud83c\udfae Need buffs/debuffs system Effects System - Designer-friendly ScriptableObjects ~5 minutes \ud83d\udd0d Slow spatial searches Spatial Trees - O(log n) queries ~5 minutes \ud83c\udfb2 Random is too slow/limited PRNG.Instance - 10-15x faster in benchmarks ~1 minute \ud83d\udcbe Need save/load system Serialization - Unity types just work ~10 minutes \ud83d\udee0\ufe0f Manual sprite workflows Editor Tools - 20+ automation tools ~3 minutes Not sure where to start? \u2192 Getting Started Guide walks through the top 3 features in 5 minutes.
"},{"location":"readme/#top-time-savers","title":"\u26a1 Top Time-Savers","text":"These features reduce entire categories of repetitive work. Pick one that solves your immediate pain:
"},{"location":"readme/#1-inspector-tooling","title":"1. \ud83c\udfa8 Inspector Tooling","text":"\u23f1\ufe0f 5-10 min/script \u00d7 200 scripts = ~20 hours saved on custom editors
Declarative inspector attributes reduce the need for custom PropertyDrawers and EditorGUI code:
C#// \u274c OLD WAY: 100+ lines of custom editor code\n[CustomEditor(typeof(CharacterStats))]\npublic class CharacterStatsEditor : Editor {\n // ... SerializedProperty declarations ...\n // ... OnEnable setup ...\n // ... OnInspectorGUI with EditorGUI.BeginFoldoutHeaderGroup ...\n // ... Custom button rendering ...\n // ... Conditional field display logic ...\n}\n\n// \u2705 NEW WAY: Declarative attributes, zero custom editors\npublic class CharacterStats : MonoBehaviour\n{\n [WGroup(\"combat\", \"Combat Stats\", collapsible: true)]\n public float maxHealth = 100f;\n [WGroupEnd(\"combat\")] // defense IS included, then group closes\n public float defense = 10f;\n\n [WGroup(\"abilities\", \"Abilities\", collapsible: true, startCollapsed: true)]\n [System.Flags] public enum Powers { None = 0, Fly = 1, Strength = 2, Speed = 4 }\n [WEnumToggleButtons(showSelectAll: true, buttonsPerRow: 3)]\n [WGroupEnd(\"abilities\")] // currentPowers IS included, then group closes\n public Powers currentPowers;\n\n public enum WeaponType { Melee, Ranged, Magic }\n public WeaponType weaponType;\n\n [WShowIf(nameof(weaponType), WShowIfComparison.Equal, WeaponType.Ranged)]\n public int ammoCapacity = 30;\n\n [WButton(\"Heal to Full\", groupName: \"Debug\")]\n private void HealToFull() { maxHealth = 100f; }\n}\nFeatures:
\ud83d\udcd6 Complete Inspector Guide | \ud83d\udd04 Odin Migration Guide
"},{"location":"readme/#2-auto-wire-components","title":"2. \ud83d\udd0c Auto-Wire Components","text":"\u23f1\ufe0f 10-20 min/script \u00d7 100 scripts = ~20 hours saved
Reduces GetComponent boilerplate with attribute-based auto-wiring. Replace 20+ lines with 3 attributes:
C#// \u274c OLD WAY: 20+ lines per script\nvoid Awake() {\n sprite = GetComponent<SpriteRenderer>();\n if (sprite == null) Debug.LogError(\"Missing SpriteRenderer!\");\n\n rigidbody = GetComponentInParent<Rigidbody2D>();\n if (rigidbody == null) Debug.LogError(\"Missing Rigidbody2D!\");\n\n colliders = GetComponentsInChildren<Collider2D>();\n // 15 more lines...\n}\n\n// \u2705 NEW WAY: 4 lines total\n[SiblingComponent] private SpriteRenderer sprite;\n[ParentComponent] private Rigidbody2D rigidbody;\n[ChildComponent] private Collider2D[] colliders;\nvoid Awake() => this.AssignRelationalComponents();\nBonus: Works with VContainer/Zenject/Reflex for automatic DI + relational wiring!
\ud83d\udcd6 Learn More | See Samples~/DI - VContainer, Samples~/DI - Zenject, and Samples~/DI - Reflex folders in the repository for DI examples
\u23f1\ufe0f 2-4 hours/effect \u00d7 50 effects = ~150 hours saved
Designers create buffs/debuffs as ScriptableObjects. Zero programmer time after 20-minute setup:
C#// Create once (ScriptableObject in editor):\n// - HasteEffect: Speed \u00d7 1.5, duration 5s, tag \"Haste\", particle effect\n\n// Use everywhere:\nplayer.ApplyEffect(hasteEffect); // Apply buff\nif (player.HasTag(\"Stunned\")) return; // Query state\nplayer.RemoveEffects(player.GetHandlesWithTag(\"Haste\")); // Batch removal\nWhat you get:
Beyond buffs: Tags become a flexible capability system for AI decisions, permission gates, state management, and complex gameplay interactions (invulnerability, stealth, elemental systems).
\ud83d\udcd6 Full Guide | \ud83d\ude80 5-Minute Tutorial
"},{"location":"readme/#4-unity-aware-serialization","title":"4. \ud83d\udcbe Unity-Aware Serialization","text":"\u23f1\ufe0f 40+ hours on initial implementation + prevents player data loss
JSON/Protobuf that understands Vector3, GameObject, Color - no custom converters needed:
// Vector3, Color, GameObject references just work:\nvar saveData = new SaveData {\n playerPosition = new Vector3(1, 2, 3),\n playerColor = Color.cyan,\n inventory = new List<GameObject>()\n};\n\n// One line to save:\nbyte[] data = Serializer.JsonSerialize(saveData);\n\n// Schema evolution = never break old saves:\n[ProtoMember(1)] public int gold;\n[ProtoMember(2)] public Vector3 position;\n// Adding new field? Old saves still load!\n[ProtoMember(3)] public int level; // Safe to add\nReal-world impact: Ship updates without worrying about corrupting player saves.
\ud83d\udcd6 Serialization Guide
"},{"location":"readme/#5-object-pooling","title":"5. \ud83c\udfb1 Object Pooling","text":"\u23f1\ufe0f Reduces GC spikes = 5-10 FPS improvement in complex scenes
Zero-allocation queries with automatic cleanup. Thread-safe pooling in one line:
C#// Get pooled buffer - automatically returned on scope exit\nvoid ProcessEnemies(QuadTree2D<Enemy> enemyTree) {\n using var lease = Buffers<Enemy>.List.Get(out List<Enemy> buffer);\n\n // Use it for spatial query - zero allocations!\n enemyTree.GetElementsInRange(playerPos, 10f, buffer);\n\n foreach (Enemy enemy in buffer) {\n enemy.TakeDamage(5f);\n }\n\n // Buffer automatically returned to pool here - no cleanup needed\n}\nWhy this matters:
\ud83d\udcd6 Buffering Pattern
"},{"location":"readme/#6-editor-tools-suite","title":"6. \ud83d\udee0\ufe0f Editor Tools Suite","text":"\u23f1\ufe0f 1-2 hours/operation \u00d7 weekly use = ~100 hours/year
20+ tools that automate sprite cropping, animation creation, atlas generation, prefab validation:
Common workflows:
walk_0001.png) \u2192 1 minute (was: 20 minutes)\ud83d\udcd6 Editor Tools Guide
"},{"location":"readme/#batteries-included-extensions","title":"\ud83c\udf81 Batteries-Included Extensions","text":"Unity Helpers includes 200+ extension methods for common Unity operations:
"},{"location":"readme/#unity-type-extensions","title":"Unity Type Extensions","text":"C#// Color averaging (4 methods: LAB, HSV, Weighted, Dominant)\nColor teamColor = sprite.GetAverageColor(ColorAveragingMethod.LAB); // Perceptually accurate\n\n// Collider auto-fitting\npolygonCollider.UpdateShapeToSprite(); // Instant sprite \u2192 collider sync\n\n// Smooth direction rotation (returns rotated direction vector)\nVector2 facing = Helpers.GetAngleWithSpeed(targetDirection, currentFacing, rotationSpeed);\n\n// Safe destruction (works in editor AND runtime)\ngameObject.SmartDestroy(); // No more #if UNITY_EDITOR everywhere\n\n// Camera world bounds\nBounds visibleArea = Camera.main.OrthographicBounds(); // For culling/spawning\n\n// Predictive targeting (intercept moving targets)\nVector2 aimPoint = target.PredictCurrentTarget(shooter.position, projectileSpeed, predictiveFiring: true, targetVelocity);\nturret.transform.up = (aimPoint - (Vector2)shooter.position).normalized;\n// Positive modulo (no more negative results!)\nint index = (-1).PositiveMod(array.Length); // 4, not -1\n\n// Wrapped add for ring buffers\nindex = index.WrappedAdd(2, capacity); // Handles overflow correctly\n\n// Approximate equality with tolerance\nif (transform.position.x.Approximately(target.x, 0.01f)) { /* close enough */ }\n\n// Polyline simplification (Douglas\u2013Peucker)\nList<Vector2> simplified = LineHelper.Simplify(path, epsilon: 0.5f); // Reduce pathfinding waypoints\n// Infinite iterator (no extra allocation)\nforeach (var item in itemList.Infinite()) { /* cycles infinitely */ }\n\n// Aggregate bounds from multiple renderers\nBounds? combined = renderers.Select(r => r.bounds).GetBounds();\n\n// String similarity for fuzzy search\nint distance = playerName.LevenshteinDistance(\"jon\"); // \"john\" = 1, close match!\n\n// Case conversions (6 styles: Pascal, Camel, Snake, Kebab, Title, Constant)\nstring apiKey = \"user_name\".ToPascalCase(); // \"UserName\"\nFull list: Math & Extensions Guide | Reflection Helpers
"},{"location":"readme/#additional-utilities","title":"\ud83d\udc8e Additional Utilities","text":"These utilities solve specific problems that waste hours if you implement them yourself:
Feature What It Does Time Saved Predictive Targeting Accurate ballistics for turrets/missiles in one call 2-3 hours per shooting system Coroutine Jitter Prevents 100 enemies polling on same frame Reduces frame spikes IL-Emitted Reflection Up to 12x faster than System.Reflection for method invocations, IL2CPP safe Critical for serialization/modding SmartDestroy() Editor/runtime safe destruction (no scene corruption) Prevents countless debugging hours Convex/Concave Hulls Generate territory borders from point clouds 4-6 hours per hull algorithm Logging Extensions Rich tags, thread-aware logs, per-object toggles Keeps consoles readable + actionable"},{"location":"readme/#design-philosophy","title":"Design Philosophy","text":"Unity Helpers reduces repetitive work by providing tested utilities for common Unity patterns, including GetComponent boilerplate, spatial query loops, and save/load systems.
Built for Real Projects:
Who This Is For:
Unity Helpers is available from multiple sources. Choose the one that best fits your workflow:
Source Best For Auto-Updates OpenUPM Most users, easy version management \u2705 Yes Git URL Latest commits, CI/CD pipelines \u2705 Yes NPM Registry Teams already using NPM \u2705 Yes Source Offline, modifications needed \u274c Manual"},{"location":"readme/#from-openupm-recommended","title":"From OpenUPM (Recommended)","text":"OpenUPM is the recommended installation method for easy version management and updates.
"},{"location":"readme/#option-a-via-package-manager-ui","title":"Option A: Via Package Manager UI","text":"OpenUPMhttps://package.openupm.comcom.wallstop-studiosUnity HelpersIf you have the OpenUPM CLI installed:
Bashopenupm add com.wallstop-studios.unity-helpers\nAdd to your Packages/manifest.json:
{\n \"scopedRegistries\": [\n {\n \"name\": \"OpenUPM\",\n \"url\": \"https://package.openupm.com\",\n \"scopes\": [\"com.wallstop-studios\"]\n }\n ],\n \"dependencies\": {\n \"com.wallstop-studios.unity-helpers\": \"3.1.0\"\n }\n}\nInstall directly from GitHub for the latest version:
https://github.com/wallstop/unity-helpers.gitOR add to your Packages/manifest.json:
{\n \"dependencies\": {\n \"com.wallstop-studios.unity-helpers\": \"https://github.com/wallstop/unity-helpers.git\"\n }\n}\nTip: To lock to a specific version, append #3.1.0 to the URL.
NPMhttps://registry.npmjs.orgcom.wallstop-studioscom.wallstop-studios.unity-helpers.unitypackage from GitHub Releases.unitypackage file and importAssets/ or Packages/ folderUnity Helpers is multiplatform compatible including:
Requirements:
Unity Helpers includes a SINGLE_THREADED scripting define symbol for WebGL and other single-threaded environments. When enabled, the library automatically uses optimized code paths that eliminate threading overhead:
Optimized systems with SINGLE_THREADED:
Stack<T> and Dictionary<T> instead of ConcurrentBag<T> and ConcurrentDictionary<T>ThreadLocal<T>How to enable:
Unity automatically defines UNITY_WEBGL for WebGL builds. To enable SINGLE_THREADED optimization:
SINGLE_THREADED for WebGL platformcsc.rsp file: -define:SINGLE_THREADEDPerformance impact: 10-20% faster hot path operations on single-threaded platforms by avoiding unnecessary synchronization overhead.
"},{"location":"readme/#il2cpp-and-code-stripping-considerations","title":"IL2CPP and Code Stripping Considerations","text":"\u26a0\ufe0f Important for IL2CPP builds (WebGL, Mobile, Consoles):
Some features in Unity Helpers use reflection internally (particularly Protobuf serialization and ReflectionHelpers). IL2CPP's managed code stripping may remove types/members that are only accessed via reflection, causing runtime errors.
Symptoms of stripping issues:
NullReferenceException or TypeLoadException during deserializationCreate a link.xml file in your Assets folder to prevent stripping:
<linker>\n <!-- Preserve your serialized types -->\n <assembly fullname=\"Assembly-CSharp\">\n <type fullname=\"MyNamespace.PlayerSave\" preserve=\"all\"/>\n <type fullname=\"MyNamespace.InventoryData\" preserve=\"all\"/>\n <!-- Add all Protobuf-serialized types here -->\n </assembly>\n\n <!-- Preserve Unity Helpers if needed -->\n <assembly fullname=\"WallstopStudios.UnityHelpers.Runtime\" preserve=\"all\"/>\n</linker>\nBest practices:
[ProtoContract] should be preservedWhen you don't need link.xml:
Related documentation:
\ud83d\udca1 First time? Skip to section #2 (Relational Components) - it has the biggest immediate impact.
Already read the Top 5 Time-Savers? Jump directly to the Core Features reference below, or check out the Getting Started Guide.
"},{"location":"readme/#core-features","title":"Core Features","text":""},{"location":"readme/#random-number-generators","title":"Random Number Generators","text":"Unity Helpers includes 15 high-quality random number generators, all implementing a rich IRandom interface:
The tables below are auto-generated by the performance benchmark. Run RandomPerformanceTests.Benchmark in the Unity Test Runner to refresh them.
No benchmark data available yet. Run RandomPerformanceTests.Benchmark to populate these tables.
All generators implement IRandom with the following functionality:
IRandom random = PRNG.Instance;\n\n// Basic types\nint i = random.Next(); // int in [0, int.MaxValue]\nint range = random.Next(10, 20); // int in [10, 20)\nuint ui = random.NextUint(); // uint in [0, uint.MaxValue]\nfloat f = random.NextFloat(); // float in [0.0f, 1.0f]\ndouble d = random.NextDouble(); // double in [0.0d, 1.0d]\nbool b = random.NextBool(); // true or false\n\n// Unity types\nVector2 v2 = random.NextVector2(); // Random 2D vector\nVector3 v3 = random.NextVector3(); // Random 3D vector\nColor color = random.NextColor(); // Random color\nQuaternion rot = random.NextRotation(); // Random rotation\n\n// Distributions\nfloat gaussian = random.NextGaussian(mean: 0f, stdDev: 1f);\n\n// Collections\nT item = random.NextOf(collection); // Random element\nT[] shuffled = random.Shuffle(array); // Fisher-Yates shuffle\nint weightedIndex = random.NextWeightedIndex(weights);\n\n// Special\nGuid uuid = random.NextGuid(); // UUIDv4\nT enumValue = random.NextEnum<T>(); // Random enum value\nfloat[,] noise = random.NextNoiseMap(width, height); // Perlin noise\nAll generators are seedable for replay systems:
C#// Create seeded generator for deterministic behavior\nIRandom seededRandom = new IllusionFlow(seed: 12345);\n\n// Same seed = same sequence\nIRandom replay = new IllusionFlow(seed: 12345);\n// Both will generate identical values\nThreading:
PRNG.Instance for a thread-local default, or use each generator's TypeName.Instance (e.g., IllusionFlow.Instance, PcgRandom.Instance).\ud83d\udcca Performance Comparison
"},{"location":"readme/#spatial-trees","title":"Spatial Trees","text":"Efficient spatial data structures for 2D and 3D games.
"},{"location":"readme/#2d-spatial-trees","title":"2D Spatial Trees","text":"using WallstopStudios.UnityHelpers.Core.DataStructure;\n\n// Create from collection\nGameObject[] objects = FindObjectsOfType<GameObject>();\nQuadTree2D<GameObject> tree = new(objects, go => go.transform.position);\n\n// Query by radius\nList<GameObject> nearby = new();\ntree.GetElementsInRange(playerPos, radius: 10f, nearby);\n\n// Query by bounds\nBounds searchArea = new(center, size);\ntree.GetElementsInBounds(searchArea, nearby);\n\n// Find nearest neighbors (approximate, but fast)\ntree.GetApproximateNearestNeighbors(playerPos, count: 5, nearby);\nNote: KdTree3D, OctTree3D, and RTree3D are under active development. SpatialHash3D is stable and production\u2011ready.
// Same API as 2D, but with Vector3\nVector3[] positions = GetAllPositions();\nOctTree3D<Vector3> tree = new(positions, p => p);\n\nList<Vector3> results = new();\ntree.GetElementsInRange(center, radius: 50f, results);\n\u2705 Good for:
\u274c Not ideal for:
\ud83d\udcca 2D Benchmarks | \ud83d\udcca 3D Benchmarks
For behavior details and edge cases, see: Spatial Tree Semantics
"},{"location":"readme/#relational-components","title":"Relational Components","text":"Auto-wire components using attributes to reduce GetComponent boilerplate.
Key attributes:
[SiblingComponent] - Find components on same GameObject[ParentComponent] - Find components in parent hierarchy[ChildComponent] - Find components in children[ValidateAssignment] - Validate at edit time, show errors in inspector[WNotNull] - Must be assigned in inspector[WReadOnly] - Read-only display in inspector[WInLineEditor] - Inline inspector editing for object references[WShowIf] - Conditional display based on field valuesQuick example:
C#using WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class Enemy : MonoBehaviour\n{\n // Find on same GameObject\n [SiblingComponent]\n private Animator animator;\n\n // Find in parent\n [ParentComponent]\n private EnemySpawner spawner;\n\n // Find in children\n [ChildComponent]\n private List<Weapon> weapons;\n\n // Optional component (no error if missing)\n [SiblingComponent(Optional = true)]\n private AudioSource audioSource;\n\n // Only search direct children/parents\n [ParentComponent(OnlyAncestors = true)]\n private Transform[] parentHierarchy;\n\n // Include inactive components\n [ChildComponent(IncludeInactive = true)]\n private ParticleSystem[] effects;\n\n private void Awake()\n {\n this.AssignRelationalComponents();\n }\n}\nSee the in-depth guide: Relational Components. Performance snapshots: Relational Component Performance Benchmarks.
"},{"location":"readme/#effects-attributes-and-tags","title":"Effects, Attributes, and Tags","text":"Create data-driven gameplay effects that modify stats, apply tags, and drive cosmetics.
Key pieces:
AttributeEffect \u2014 ScriptableObject that bundles stat changes, tags, cosmetics, and duration.EffectHandle \u2014 Unique ID for one application instance; remove/refresh specific stacks.AttributesComponent \u2014 Base class for components that expose modifiable Attribute fields.TagHandler \u2014 Counts and queries string tags for gating gameplay (e.g., \"Stunned\").CosmeticEffectData \u2014 Prefab-like container of behaviors shown while an effect is active.Quick example:
C#using WallstopStudios.UnityHelpers.Tags;\n\n// 1) Define stats on a component\npublic class CharacterStats : AttributesComponent\n{\n public Attribute Health = 100f;\n public Attribute Speed = 5f;\n}\n\n// 2) Author an AttributeEffect (ScriptableObject) in the editor\n// - modifications: [ { attribute: \"Speed\", action: Multiplication, value: 1.5f } ]\n// - durationType: Duration, duration: 5\n// - effectTags: [ \"Haste\" ]\n// - cosmeticEffects: [ a prefab with CosmeticEffectData + Particle/Audio components ]\n\n// 3) Apply and later remove\nGameObject player = ...;\nAttributeEffect haste = ...; // ScriptableObject reference\nEffectHandle? handle = player.ApplyEffect(haste);\nif (handle.HasValue)\n{\n // Remove early if needed\n player.RemoveEffect(handle.Value);\n}\n\n// Query tags anywhere\nif (player.HasTag(\"Stunned\")) { /* disable input */ }\nDetails at a glance:
ModifierDurationType.Instant \u2014 applies permanently; returns null handle.ModifierDurationType.Duration \u2014 temporary; expires automatically; reapply can reset if enabled.ModifierDurationType.Infinite \u2014 persists until RemoveEffect(handle) is called.AttributeModification order: Addition \u2192 Multiplication \u2192 Override.CosmeticEffectData.RequiresInstancing \u2014 instance per application or reuse shared presenters.Power Pattern: Tags aren't just for buffs\u2014use them to build capability systems for invulnerability, AI decision-making, permission gates, state management, and elemental interactions. See Advanced Scenarios for patterns.
Further reading: see the full guide Effects System.
"},{"location":"readme/#serialization","title":"Serialization","text":"Fast, compact serialization for save systems, config, and networking.
This package provides three serialization technologies:
Json \u2014 Uses System.Text.Json with built\u2011in converters for Unity types.Protobuf \u2014 Uses protobuf-net for compact, fast, schema\u2011evolvable binary.SystemBinary \u2014 Uses .NET BinaryFormatter for legacy/ephemeral data only.All are exposed via WallstopStudios.UnityHelpers.Core.Serialization.Serializer.
using System.Collections.Generic;\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Serialization;\n\npublic class SaveData\n{\n public Vector3 position;\n public Color playerColor;\n public List<GameObject> inventory;\n}\n\nvar data = new SaveData\n{\n position = new Vector3(1, 2, 3),\n playerColor = Color.cyan,\n inventory = new List<GameObject>()\n};\n\n// Serialize to UTF\u20118 JSON bytes (Unity types supported via built\u2011in converters)\nbyte[] jsonBytes = Serializer.JsonSerialize(data);\n\n// Deserialize from string\nstring jsonText = Serializer.JsonStringify(data, pretty: true);\nSaveData fromText = Serializer.JsonDeserialize<SaveData>(jsonText);\n\n// File helpers\nSerializer.WriteToJsonFile(data, path: \"save.json\", pretty: true);\nSaveData fromFile = Serializer.ReadFromJsonFile<SaveData>(\"save.json\");\n\n// Generic entry points (choose format at runtime)\nbyte[] bytes = Serializer.Serialize(data, SerializationType.Json);\nSaveData loaded = Serializer.Deserialize<SaveData>(bytes, SerializationType.Json);\nusing ProtoBuf; // protobuf-net\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Serialization;\n\n[ProtoContract]\npublic class NetworkMessage\n{\n [ProtoMember(1)] public int playerId;\n [ProtoMember(2)] public Vector3 position; // Vector3 works in Protobuf via built-in surrogates\n}\n\nvar message = new NetworkMessage { playerId = 7, position = new Vector3(5, 0, -2) };\n\n// Protobuf bytes (small + fast)\nbyte[] bytes = Serializer.ProtoSerialize(message);\nNetworkMessage decoded = Serializer.ProtoDeserialize<NetworkMessage>(bytes);\n\n// Generic entry points\nbyte[] bytes2 = Serializer.Serialize(message, SerializationType.Protobuf);\nNetworkMessage decoded2 = Serializer.Deserialize<NetworkMessage>(bytes2, SerializationType.Protobuf);\n\n// Buffer reuse (reduce GC for hot paths)\nbyte[] buffer = null;\nint len = Serializer.Serialize(message, SerializationType.Protobuf, ref buffer);\nNetworkMessage again = Serializer.Deserialize<NetworkMessage>(buffer.AsSpan(0, len).ToArray(), SerializationType.Protobuf);\nNotes:
[ProtoMember(n)] and never reuse or renumber.Features:
Runtime/Utils/LZMA.cs)Full guide: Serialization
"},{"location":"readme/#data-structures","title":"Data Structures","text":"Additional high-performance data structures:
Structure Use Case CyclicBuffer Ring buffer, sliding windows BitSet Compact boolean storage ImmutableBitSet Read-only bit flags Heap Priority queue operations PriorityQueue Event scheduling Deque Double-ended queue DisjointSet Union-find operations Trie String prefix trees SparseSet Fast add/remove with iteration TimedCache Auto-expiring cache C#// Cyclic buffer for damage history\nCyclicBuffer<float> damageHistory = new(capacity: 10);\ndamageHistory.Add(25f);\ndamageHistory.Add(30f);\nfloat avgDamage = damageHistory.Average();\n\n// Priority queue for event scheduling (priority determined by comparer)\nPriorityQueue<GameEvent> eventQueue = new(\n Comparer<GameEvent>.Create((a, b) => b.Priority.CompareTo(a.Priority)) // Higher first\n);\neventQueue.Enqueue(spawnEvent);\neventQueue.Enqueue(bossEvent);\nif (eventQueue.TryDequeue(out GameEvent next)) { /* process event */ }\n\n// Trie for autocomplete\nTrie commandTrie = new();\ncommandTrie.Insert(\"teleport\");\ncommandTrie.Insert(\"tell\");\ncommandTrie.Insert(\"terrain\");\nList<string> matches = commandTrie.GetWordsWithPrefix(\"tel\");\n// Returns: [\"teleport\", \"tell\"]\nFull guide: Data Structures
"},{"location":"readme/#core-math-extensions","title":"Core Math & Extensions","text":"Numeric helpers, geometry primitives, Unity extensions, colors, collections, strings, directions.
See the guide: Core Math & Extensions.
"},{"location":"readme/#at-a-glance","title":"At a Glance","text":"PositiveMod, WrappedAdd \u2014 Safe cyclic arithmetic for indices/angles.LineHelper.Simplify \u2014 Reduce polyline vertices with Douglas\u2013Peucker.Line2D.Intersects \u2014 2D segment intersection and closest-point helpers.RectTransform.GetWorldRect \u2014 Axis-aligned world bounds for rotated UI.Camera.OrthographicBounds \u2014 Compute visible world bounds for ortho cameras.Color.GetAverageColor \u2014 LAB/HSV/Weighted/Dominant color averaging.IEnumerable.Infinite \u2014 Cycle sequences without extra allocations.StringExtensions.LevenshteinDistance \u2014 Edit distance for fuzzy matching.RuntimeSingleton<T> \u2014 Global component singleton with optional cross\u2011scene persistence.ScriptableObjectSingleton<T> \u2014 Global settings/data singleton loaded from Resources/, auto\u2011created by the editor tool.See the guide: Singleton Utilities and the tool: ScriptableObject Singleton Creator.
"},{"location":"readme/#editor-tools","title":"Editor Tools","text":"Unity Helpers includes 20+ editor tools to streamline your workflow:
Tools > Wallstop Studios > Unity Helpers > Request Script Compilation or use the default shortcut (Ctrl/Cmd + Alt + R) registered with Unity\u2019s Shortcut Manager (listed under Wallstop / Request Script Compilation). The shortcut now forces an AssetDatabase.Refresh before requesting compilation and logs whenever Unity is already compiling, so scripts added outside the editor are imported even while Unity is unfocused.\ud83d\udcd6 Complete Editor Tools Documentation
Quick Access:
Tools > Wallstop Studios > Unity HelpersAssets > Create > Wallstop Studios > Unity HelpersZero-allocation queries with automatic cleanup and thread-safe pooling.
C#using WallstopStudios.UnityHelpers.Utils;\nusing WallstopStudios.UnityHelpers.Core.DataStructure;\n\n// Example: Use pooled buffer for spatial query\nvoid FindNearbyEnemies(QuadTree2D<Enemy> tree, Vector2 position)\n{\n // Get pooled list - automatically returned when scope exits\n using var lease = Buffers<Enemy>.List.Get(out List<Enemy> buffer);\n\n // Use it with spatial query - combines zero-alloc query + pooled buffer!\n tree.GetElementsInRange(position, 10f, buffer);\n\n foreach (Enemy enemy in buffer)\n {\n enemy.TakeDamage(5f);\n }\n // buffer automatically returned to pool here\n}\n\n// Array pooling example\nvoid ProcessLargeDataset(int size)\n{\n using var lease = WallstopArrayPool<float>.Get(size, out float[] buffer);\n\n // Use buffer for temporary processing\n for (int i = 0; i < size; i++)\n {\n buffer[i] = ComputeValue(i);\n }\n\n // buffer automatically returned to pool here\n}\nDo / Don'ts:
Buffers<T> \u2014 pooled collections (List/Stack/Queue/HashSet) with PooledResource leases.using var lease = Buffers<Foo>.List.Get(out List<Foo> list);using var lease = Buffers<Foo>.Stack.Get(out Stack<Foo> stack);using var lease = Buffers<Foo>.HashSet.Get(out HashSet<Foo> set);Pattern: acquire \u2192 use \u2192 Dispose (returns to pool, clears collection).
WallstopArrayPool<T> \u2014 rent arrays by length with automatic return on dispose.
using var lease = WallstopArrayPool<int>.Get(1024, out int[] buffer);Use for temporary processing buffers, sorting, or interop with APIs that require arrays.
WallstopFastArrayPool<T> \u2014 fast array pool specialized for frequent short\u2011lived arrays (requires T : unmanaged), does not clear arrays. Returned arrays may have previous content in them.
using var lease = WallstopFastArrayPool<int>.Get(count, out int[] buffer);How pooling + buffering help APIs:
List<T> to GetElementsInRange/GetElementsInBounds and iterate results without allocations.GetComponents(buffer) clears and fills your buffer instead of allocating arrays.Auto-detected packages:
com.extenject.zenject, com.modesttree.zenject, com.svermeulen.extenjectjp.cysharp.vcontainer, jp.hadashikick.vcontainercom.gustavopsantos.reflexManual or source imports (no UPM):
Project Settings > Player > Other Settings > Scripting Define Symbols:ZENJECT_PRESENT when Zenject/Extenject is presentVCONTAINER_PRESENT when VContainer is presentREFLEX_PRESENT when Reflex is presentNotes:
Runtime/Integrations/* compile automatically and expose helpers like RelationalComponentsInstaller (Zenject/Reflex) and RegisterRelationalComponents() (VContainer).versionDefines in the asmdefs.Quick start:
LifetimeScope.Configure, call builder.RegisterRelationalComponents().RelationalComponentsInstaller to your SceneContext (toggle scene scan if desired).RelationalComponentsInstaller on the same GameObject as your SceneScope to bind the assigner, run the scene scan, and (optionally) listen for additive scenes. Use container.InjectWithRelations(...) / InstantiateGameObjectWithRelations(...) for DI-friendly hydration.// VContainer \u2014 LifetimeScope\nusing VContainer;\nusing VContainer.Unity;\nusing WallstopStudios.UnityHelpers.Integrations.VContainer;\n\nprotected override void Configure(IContainerBuilder builder)\n{\n // Register assigner + one-time scene scan + additive listener (default)\n builder.RegisterRelationalComponents(\n RelationalSceneAssignmentOptions.Default,\n enableAdditiveSceneListener: true\n );\n}\n\n// Zenject \u2014 prefab instantiation with DI + relations\nusing Zenject;\nusing WallstopStudios.UnityHelpers.Integrations.Zenject;\n\nvar enemy = Container.InstantiateComponentWithRelations(enemyPrefab, parent);\n\n// Reflex \u2014 prefab instantiation with DI + relations\nusing Reflex.Core;\nusing WallstopStudios.UnityHelpers.Integrations.Reflex;\n\nvar enemy = container.InstantiateComponentWithRelations(enemyPrefab, parent);\nSee the full guide with scenarios, troubleshooting, and testing patterns: Relational Components Guide
"},{"location":"readme/#additional-helpers","title":"Additional Helpers","text":"resolver.InjectWithRelations(component) \u2014 inject + assign a single instanceresolver.InstantiateComponentWithRelations(prefab, parent) \u2014 instantiate + inject + assignresolver.InjectGameObjectWithRelations(root, includeInactiveChildren) \u2014 inject hierarchy + assignresolver.InstantiateGameObjectWithRelations(prefab, parent) \u2014 instantiate GO + inject + assign
Zenject:
container.InjectWithRelations(component) \u2014 inject + assign a single instancecontainer.InstantiateComponentWithRelations(prefab, parent) \u2014 instantiate + assigncontainer.InjectGameObjectWithRelations(root, includeInactiveChildren) \u2014 inject hierarchy + assigncontainer.InstantiateGameObjectWithRelations(prefab, parent) \u2014 instantiate GO + inject + assign
Reflex:
container.InjectWithRelations(component) \u2014 inject + assign a single instancecontainer.InstantiateComponentWithRelations(prefab, parent) \u2014 instantiate + inject + assigncontainer.InjectGameObjectWithRelations(root, includeInactiveChildren) \u2014 inject hierarchy + assigncontainer.InstantiateGameObjectWithRelations(prefab, parent) \u2014 instantiate GO + inject + assignRegisterRelationalComponents(..., enableAdditiveSceneListener: true) registers a listener that hydrates components in newly loaded scenes.RelationalComponentsInstaller exposes a toggle \"Listen For Additive Scenes\" to register the same behavior.RelationalComponentsInstaller exposes a toggle \"Listen For Additive Scenes\" to register the same behavior.FindObjectsOfType calls by scanning once and checking type ancestry.new RelationalSceneAssignmentOptions(includeInactive: true, useSinglePassScan: true)new RelationalSceneAssignmentOptions(includeInactive: true, useSinglePassScan: true)new RelationalSceneAssignmentOptions(includeInactive: true, useSinglePassScan: true)Unity Helpers is built with performance as a top priority:
Random Number Generation:
Spatial Queries:
Memory Management:
Reflection:
System.Reflection (method invocations ~12x; boxed scenarios up to 100x)ReflectionHelpers.OverrideReflectionCapabilities) let tests force expression/IL fallbacksList Sorting:
Ghost, Meteor, Power, Grail, Pattern-Defeating QuickSort, Insertion, Tim, Jesse, Green, Ska, Ipn, Smooth, Block, IPS4o, Power+, Glide, Flux) tuned for IList<T>Start Here:
Core Guides:
Spatial Trees:
Performance & Reference:
Project Info:
Contributions are welcome! Please feel free to submit a Pull Request.
"},{"location":"readme/#formatting-assistance","title":"Formatting Assistance","text":"/format (aliases: /autofix, /lint-fix).See more details in CONTRIBUTING.
"},{"location":"readme/#license","title":"License","text":"This project is licensed under the MIT License - see the LICENSE file for details.
"},{"location":"readme/#20-release-notes-highlights","title":"2.0 Release Notes (Highlights)","text":"SerializationType.SystemBinary is [Obsolete]. Use SerializationType.Json (System.Text.Json + Unity converters) or SerializationType.Protobuf (protobuf-net) for new work. Keep BinaryFormatter for trusted, non\u2011portable data only.
GameObject JSON converter outputs structured JSON:
GameObjectConverter now writes a JSON object with name, type (assembly-qualified), and instanceId rather than a stringified placeholder.
Minor robustness improvements:
UnityEditor imports in runtime files to ensure clean player builds.See Serialization guide for AOT/IL2CPP guidance and Unity JSON options, and Editor tools guide for Editor tool usage details.
"},{"location":"contributing/testing-patterns/","title":"Testing \"Impossible\" State Patterns","text":"This guide documents patterns for testing states that \"should never happen\" but could occur in production. These tests catch edge cases that defensive programming must handle gracefully.
"},{"location":"contributing/testing-patterns/#why-test-impossible-states","title":"Why Test \"Impossible\" States","text":"Production code encounters situations that seem impossible during development:
Testing these scenarios ensures code fails gracefully rather than crashing or corrupting data.
"},{"location":"contributing/testing-patterns/#destroyed-unity-objects","title":"Destroyed Unity Objects","text":"Unity objects can be destroyed at any time by external systems. Code must handle the \"fake null\" state where an object reference is not null in C# terms but returns true for Unity's null check.
[Test]\npublic void GetGameObjectHandlesDestroyedComponent()\n{\n GameObject go = Track(new GameObject(\"Test\", typeof(SpriteRenderer)));\n SpriteRenderer spriteRenderer = go.GetComponent<SpriteRenderer>();\n\n Object.DestroyImmediate(spriteRenderer); // UNH-SUPPRESS: Test verifies behavior after component destruction\n\n GameObject result = spriteRenderer.GetGameObject();\n\n Assert.IsTrue(result == null, \"Should return null for destroyed component\");\n}\nFrom /workspaces/com.wallstop-studios.unity-helpers/Tests/Runtime/Extensions/UnityExtensionsBasicTests.cs:
[Test]\npublic void GetCenterUsesCenterPointOffsetWhenAvailable()\n{\n GameObject go = Track(new GameObject(\"CenterPointTest\", typeof(CenterPointOffset)));\n\n go.transform.position = new Vector3(5f, 5f, 0f);\n CenterPointOffset offset = go.GetComponent<CenterPointOffset>();\n offset.offset = new Vector2(3f, 4f);\n\n Assert.AreEqual(offset.CenterPoint, go.GetCenter());\n\n Object.DestroyImmediate(offset); // UNH-SUPPRESS: Test verifies behavior after component destruction\n Assert.AreEqual((Vector2)go.transform.position, go.GetCenter());\n}\nThis test verifies that GetCenter() falls back to the GameObject's transform position when the CenterPointOffset component is destroyed.
From /workspaces/com.wallstop-studios.unity-helpers/Tests/Runtime/Helper/ObjectHelperTests.cs:
[UnityTest]\npublic IEnumerator GetGameObject()\n{\n GameObject go = Track(new GameObject(\"Test\", typeof(SpriteRenderer)));\n SpriteRenderer spriteRenderer = go.GetComponent<SpriteRenderer>();\n\n GameObject result = go.GetGameObject();\n Assert.AreEqual(result, go);\n result = spriteRenderer.GetGameObject();\n Assert.AreEqual(result, go);\n\n Object.DestroyImmediate(spriteRenderer); // UNH-SUPPRESS: Test verifies behavior after component destruction\n result = spriteRenderer.GetGameObject();\n Assert.IsTrue(result == null);\n result = go.GetGameObject();\n Assert.AreEqual(result, go);\n\n Object.DestroyImmediate(go); // UNH-SUPPRESS: Test verifies behavior after GameObject destruction\n result = spriteRenderer.GetGameObject();\n Assert.IsTrue(result == null);\n result = go.GetGameObject();\n Assert.IsTrue(result == null);\n\n result = ((GameObject)null).GetGameObject();\n Assert.IsTrue(result == null);\n\n result = ((SpriteRenderer)null).GetGameObject();\n Assert.IsTrue(result == null);\n yield break;\n}\nThis test verifies:
Editor code often works with SerializedObject and SerializedProperty. When the target object is destroyed, these become invalid but may not be null.
[Test]\npublic void DrawerHandlesDestroyedSerializedObjectTarget()\n{\n MyScriptableObject target = CreateScriptableObject<MyScriptableObject>();\n SerializedObject serializedObject = new SerializedObject(target);\n SerializedProperty property = serializedObject.FindProperty(\"myField\");\n\n Object.DestroyImmediate(target); // UNH-SUPPRESS: Test verifies behavior after target destroyed\n\n // SerializedObject.targetObject is now null\n Assert.DoesNotThrow(() => drawer.OnGUI(rect, property, label));\n}\nFrom /workspaces/com.wallstop-studios.unity-helpers/Tests/Editor/CustomDrawers/ScriptableSingletonSerializationTests.cs:
[Test]\npublic void IsScriptableSingletonTypeWithDestroyedObjectReturnsFalse()\n{\n RegularScriptableObject target = CreateScriptableObject<RegularScriptableObject>();\n Object.DestroyImmediate(target); // UNH-SUPPRESS: Testing destroyed object handling\n\n // Unity's null check should handle destroyed objects\n bool result = SerializableDictionaryPropertyDrawer.IsScriptableSingletonType(target);\n Assert.IsFalse(result, \"Destroyed object should return false (Unity null check).\");\n}\nFrom /workspaces/com.wallstop-studios.unity-helpers/Tests/Editor/Utils/WButton/WButtonRenderingTests.cs:
[Test]\npublic void NullEditorTargetHandledGracefully()\n{\n RenderingTargetSingleButton asset = Track(\n ScriptableObject.CreateInstance<RenderingTargetSingleButton>()\n );\n UnityEditor.Editor editor = Track(UnityEditor.Editor.CreateEditor(asset));\n Dictionary<WButtonGroupKey, WButtonPaginationState> paginationStates = new();\n Dictionary<WButtonGroupKey, bool> foldoutStates = new();\n\n Object.DestroyImmediate(asset); // UNH-SUPPRESS: Test verifies behavior when target is destroyed\n _trackedObjects.Remove(asset);\n\n bool drawn = WButtonGUI.DrawButtons(\n editor,\n WButtonPlacement.Top,\n paginationStates,\n foldoutStates,\n UnityHelpersSettings.WButtonFoldoutBehavior.AlwaysOpen,\n triggeredContexts: null,\n globalPlacementIsTop: true\n );\n\n Assert.That(drawn, Is.False, \"Should return false when target is destroyed\");\n}\nReferences that \"can't be null\" sometimes become null due to serialization issues, race conditions, improper initialization, or user error. Robust code must handle these cases gracefully.
"},{"location":"contributing/testing-patterns/#pattern-explicit-null-input-handling","title":"Pattern: Explicit Null Input Handling","text":"Test that methods handle null inputs gracefully, even when callers are \"supposed to\" provide non-null values.
C#[Test]\npublic void ProcessNullInputDoesNotThrow()\n{\n Assert.DoesNotThrow(() => Processor.Process(null));\n}\n\n[Test]\npublic void ProcessNullInputReturnsDefault()\n{\n var result = Processor.Process(null);\n Assert.AreEqual(default(MyType), result);\n}\nFrom /workspaces/com.wallstop-studios.unity-helpers/Tests/Runtime/Helper/ObjectHelperTests.cs:
[UnityTest]\npublic IEnumerator GetGameObject()\n{\n GameObject go = Track(new GameObject(\"Test\", typeof(SpriteRenderer)));\n SpriteRenderer spriteRenderer = go.GetComponent<SpriteRenderer>();\n\n // ... (normal operation tests) ...\n\n // Test explicit null input handling\n result = ((GameObject)null).GetGameObject();\n Assert.IsTrue(result == null);\n\n result = ((SpriteRenderer)null).GetGameObject();\n Assert.IsTrue(result == null);\n yield break;\n}\nThis test verifies that extension methods handle explicit null inputs gracefully, returning null rather than throwing NullReferenceException.
"},{"location":"contributing/testing-patterns/#pattern-null-serialized-property-handling","title":"Pattern: Null Serialized Property Handling","text":"Editor code may receive null SerializedProperty references due to timing issues or invalid property paths.
C#[Test]\npublic void DrawPropertyHandlesNullProperty()\n{\n Assert.DoesNotThrow(() => CustomDrawer.DrawProperty(null, GUIContent.none));\n}\n\n[Test]\npublic void GetValueFromNullPropertyReturnsDefault()\n{\n object result = PropertyHelper.GetValue(null);\n Assert.IsNull(result);\n}\nCollections may contain null elements even when the code assumes they won't.
C#[Test]\npublic void ProcessCollectionWithNullElementsSucceeds()\n{\n List<string> items = new() { \"A\", null, \"B\", null, \"C\" };\n\n Assert.DoesNotThrow(() => Processor.ProcessAll(items));\n}\n\n[Test]\npublic void FilterHandlesNullElements()\n{\n List<Component> components = new() { validComponent, null, anotherValid };\n\n List<Component> filtered = ComponentFilter.FilterValid(components);\n\n Assert.That(filtered, Has.None.Null);\n Assert.AreEqual(2, filtered.Count);\n}\nEnums can hold any integer value their underlying type supports, not just defined members. This occurs when:
[Test]\npublic void DisplayNameWithInvalidEnumValue()\n{\n TestEnum invalidValue = (TestEnum)999;\n\n string displayName = invalidValue.ToDisplayName();\n\n Assert.IsNotEmpty(displayName, \"Should return some string, not crash\");\n}\n[Test]\npublic void CachedNameWithInvalidEnumValue()\n{\n TestEnum invalidValue = (TestEnum)999;\n\n string cachedName = invalidValue.ToCachedName();\n\n Assert.IsNotEmpty(cachedName);\n}\n\n[Test]\npublic void HasFlagNoAllocWithInvalidEnumValue()\n{\n TestEnum invalidValue = (TestEnum)999;\n\n Assert.IsTrue(invalidValue.HasFlagNoAlloc(invalidValue));\n Assert.IsFalse(TestEnum.First.HasFlagNoAlloc(invalidValue));\n}\nFrom /workspaces/com.wallstop-studios.unity-helpers/Tests/Runtime/Extensions/EnumExtensionTests.cs:
[Test]\npublic void DisplayNameWithInvalidEnumValue()\n{\n TestEnum invalidValue = (TestEnum)999;\n string displayName = invalidValue.ToDisplayName();\n Assert.IsNotEmpty(displayName);\n}\n\n[Test]\npublic void CachedNameWithInvalidEnumValue()\n{\n TestEnum invalidValue = (TestEnum)999;\n string cachedName = invalidValue.ToCachedName();\n Assert.IsNotEmpty(cachedName);\n}\n\n[Test]\npublic void HasFlagNoAllocWithInvalidEnumValue()\n{\n TestEnum invalidValue = (TestEnum)999;\n Assert.IsTrue(invalidValue.HasFlagNoAlloc(invalidValue));\n Assert.IsFalse(TestEnum.First.HasFlagNoAlloc(invalidValue));\n}\n[Test]\npublic void GenericSerializeInvalidSerializationTypeThrowsException()\n{\n TestMessage msg = new() { Id = 1, Name = \"Test\" };\n\n Assert.Throws<InvalidEnumArgumentException>(() =>\n Serializer.Serialize(msg, (SerializationType)999)\n );\n}\n\n[Test]\npublic void GenericDeserializeInvalidSerializationTypeThrowsException()\n{\n byte[] data = { 1, 2, 3 };\n\n Assert.Throws<InvalidEnumArgumentException>(() =>\n Serializer.Deserialize<TestMessage>(data, (SerializationType)999)\n );\n}\n[Test]\npublic void FlagsEnumShowsWhenAllFlagsSetAndExpectedIsSubset()\n{\n OdinShowIfFlagsTarget target = CreateScriptableObject<OdinShowIfFlagsTarget>();\n target.flags = (TestFlagsEnum)(-1); // All bits set\n\n (bool success, bool shouldShow) = EvaluateCondition(\n target,\n nameof(OdinShowIfFlagsTarget.flags),\n new WShowIfAttribute(\n nameof(OdinShowIfFlagsTarget.flags),\n expectedValues: new object[] { TestFlagsEnum.FlagA | TestFlagsEnum.FlagB }\n )\n );\n\n Assert.That(success, Is.True);\n Assert.That(shouldShow, Is.True, \"Field should show when all flags set and expected is subset\");\n}\nTest behavior at the boundaries of numeric types to catch overflow, underflow, and precision issues.
"},{"location":"contributing/testing-patterns/#pattern-extreme-numeric-values","title":"Pattern: Extreme Numeric Values","text":"C#[Test]\npublic void BinaryRoundTripComplexObjectAllFieldsCorrect()\n{\n ComplexMessage msg = new()\n {\n Integer = int.MaxValue,\n Double = Math.PI,\n Text = \"Complex test with unicode\",\n Data = new byte[] { 1, 2, 3, 255, 0, 128 },\n };\n\n byte[] serialized = Serializer.BinarySerialize(msg);\n ComplexMessage deserialized = Serializer.BinaryDeserialize<ComplexMessage>(serialized);\n\n Assert.AreEqual(msg.Integer, deserialized.Integer);\n Assert.AreEqual(msg.Double, deserialized.Double);\n}\nprivate static IEnumerable<TestCaseData> EdgeCaseTestData()\n{\n yield return new TestCaseData(new[] { int.MaxValue }, int.MaxValue)\n .SetName(\"Input.MaxValue.HandlesCorrectly\");\n yield return new TestCaseData(new[] { int.MinValue }, int.MinValue)\n .SetName(\"Input.MinValue.HandlesCorrectly\");\n yield return new TestCaseData(new[] { 0 }, 0)\n .SetName(\"Input.Zero.ReturnsZero\");\n yield return new TestCaseData(new[] { -1 }, -1)\n .SetName(\"Input.Negative.HandlesCorrectly\");\n}\n\n[Test]\n[TestCaseSource(nameof(EdgeCaseTestData))]\npublic void ProcessHandlesEdgeCases(int[] input, int expected)\n{\n int result = MyProcessor.Process(input);\n\n Assert.AreEqual(expected, result);\n}\nFrom /workspaces/com.wallstop-studios.unity-helpers/Tests/Runtime/Serialization/SerializerAdditionalTests.cs:
[Test]\npublic void GenericSerializeWithAllTypesEdgeCaseData()\n{\n ComplexMessage msg = new()\n {\n Integer = int.MinValue,\n Double = double.MaxValue,\n Text = string.Empty,\n Data = new byte[] { 0, 255 },\n StringList = new List<string> { \"\", \"test\" },\n Dictionary = new Dictionary<string, int> { [\"\"] = 0, [\"test\"] = -1 },\n };\n\n foreach (SerializationType type in new[]\n {\n SerializationType.SystemBinary,\n SerializationType.Protobuf,\n })\n {\n byte[] serialized = Serializer.Serialize(msg, type);\n ComplexMessage deserialized = Serializer.Deserialize<ComplexMessage>(serialized, type);\n\n Assert.AreEqual(msg.Integer, deserialized.Integer, $\"Failed for {type}\");\n Assert.AreEqual(msg.Double, deserialized.Double, $\"Failed for {type}\");\n }\n}\nTest handling of malformed, truncated, or invalid serialized data.
"},{"location":"contributing/testing-patterns/#pattern-empty-data","title":"Pattern: Empty Data","text":"C#[Test]\npublic void BinaryDeserializeEmptyArrayThrowsException()\n{\n byte[] emptyData = Array.Empty<byte>();\n\n Assert.Throws<SerializationException>(() =>\n Serializer.BinaryDeserialize<TestMessage>(emptyData)\n );\n}\n\n[Test]\npublic void ProtoDeserializeEmptyArrayReturnsDefaultInstance()\n{\n byte[] emptyData = Array.Empty<byte>();\n\n TestMessage result = Serializer.ProtoDeserialize<TestMessage>(emptyData);\n\n Assert.NotNull(result);\n Assert.AreEqual(0, result.Id);\n}\n[Test]\npublic void BinaryDeserializeCorruptedDataThrowsException()\n{\n byte[] corruptedData = { 0xFF, 0xFF, 0xFF, 0xFF };\n\n Assert.Throws<SerializationException>(() =>\n Serializer.BinaryDeserialize<TestMessage>(corruptedData)\n );\n}\n\n[Test]\npublic void FileIOReadFromInvalidJsonThrowsException()\n{\n string filePath = Path.Combine(_tempDirectory, \"invalid.json\");\n File.WriteAllText(filePath, \"{ invalid json content }\");\n\n Assert.Throws<JsonException>(() =>\n Serializer.ReadFromJsonFile<TestMessage>(filePath)\n );\n}\n[Test]\npublic void ProtoDeserializeNullDataThrowsException()\n{\n Assert.Throws<ProtoException>(() =>\n Serializer.ProtoDeserialize<TestMessage>(null)\n );\n}\n\n[Test]\npublic void ProtoDeserializeWithTypeNullDataThrowsException()\n{\n Assert.Throws<ArgumentException>(() =>\n Serializer.ProtoDeserialize<object>(null, typeof(TestMessage))\n );\n}\nMulti-threaded code can encounter states that are impossible in single-threaded execution. Unity Helpers uses #if !SINGLE_THREADED conditionals to wrap concurrent tests.
#if !SINGLE_THREADED\n[Test]\npublic void ConcurrentSetsDoNotCorruptCache()\n{\n using Cache<int, int> cache = CacheBuilder<int, int>\n .NewBuilder()\n .MaximumSize(1000)\n .Build();\n\n int threadCount = 4;\n int operationsPerThread = 250;\n CountdownEvent countdownEvent = new(threadCount);\n Exception capturedException = null;\n\n for (int t = 0; t < threadCount; t++)\n {\n int threadIndex = t;\n ThreadPool.QueueUserWorkItem(_ =>\n {\n try\n {\n for (int i = 0; i < operationsPerThread; i++)\n {\n int key = threadIndex * operationsPerThread + i;\n cache.Set(key, key);\n }\n }\n catch (Exception ex)\n {\n capturedException = ex;\n }\n finally\n {\n countdownEvent.Signal();\n }\n });\n }\n\n countdownEvent.Wait(TimeSpan.FromSeconds(10));\n\n Assert.IsTrue(capturedException == null, $\"Exception during concurrent sets: {capturedException}\");\n Assert.AreEqual(threadCount * operationsPerThread, cache.Count);\n}\n#endif\nFrom /workspaces/com.wallstop-studios.unity-helpers/Tests/Runtime/DataStructures/CacheTests.cs:
#if !SINGLE_THREADED\n[Test]\npublic void ConcurrentSetsAndGetsDoNotCorruptCache()\n{\n using Cache<int, int> cache = CacheBuilder<int, int>\n .NewBuilder()\n .MaximumSize(500)\n .Build();\n\n int threadCount = 4;\n int operationsPerThread = 500;\n CountdownEvent countdownEvent = new(threadCount);\n Exception capturedException = null;\n\n for (int t = 0; t < threadCount; t++)\n {\n int threadIndex = t;\n ThreadPool.QueueUserWorkItem(_ =>\n {\n try\n {\n for (int i = 0; i < operationsPerThread; i++)\n {\n if (i % 2 == 0)\n {\n int key = threadIndex * 100 + (i % 100);\n cache.Set(key, key);\n }\n else\n {\n int key = (threadIndex + 1) % threadCount * 100 + (i % 100);\n cache.TryGet(key, out _);\n }\n }\n }\n catch (Exception ex)\n {\n capturedException = ex;\n }\n finally\n {\n countdownEvent.Signal();\n }\n });\n }\n\n countdownEvent.Wait(TimeSpan.FromSeconds(10));\n\n Assert.IsNull(capturedException, $\"Exception during concurrent operations: {capturedException}\");\n}\n#endif\nFrom /workspaces/com.wallstop-studios.unity-helpers/Tests/Runtime/Utils/BuffersTests.cs:
#if !SINGLE_THREADED\n[Test]\npublic void WallstopFastArrayPoolConcurrentAccessRapidAllocationDeallocation()\n{\n const int iterations = 1000;\n const int threadCount = 4;\n\n CountdownEvent countdownEvent = new(threadCount);\n Exception capturedException = null;\n\n for (int t = 0; t < threadCount; t++)\n {\n ThreadPool.QueueUserWorkItem(_ =>\n {\n try\n {\n for (int i = 0; i < iterations; i++)\n {\n using (PooledArray<int> pooled = WallstopFastArrayPool<int>.Get(64, out _))\n {\n // Rapid acquire/release cycle\n }\n }\n }\n catch (Exception ex)\n {\n capturedException = ex;\n }\n finally\n {\n countdownEvent.Signal();\n }\n });\n }\n\n countdownEvent.Wait(TimeSpan.FromSeconds(30));\n Assert.IsNull(capturedException, $\"Exception during rapid allocation: {capturedException}\");\n}\n#endif\nCountdownEvent to synchronize thread completion#if !SINGLE_THREADED for WebGL/IL2CPP compatibilitySome states are logically impossible during normal execution but can occur due to reflection, serialization bugs, or corrupted data.
"},{"location":"contributing/testing-patterns/#pattern-empty-collections-where-non-empty-expected","title":"Pattern: Empty Collections Where Non-Empty Expected","text":"C#[Test]\npublic void ProcessEmptyArrayGracefully()\n{\n int[] emptyArray = Array.Empty<int>();\n\n // Methods that \"shouldn't\" receive empty arrays should handle them\n int result = collection.Min(emptyArray);\n\n Assert.AreEqual(default(int), result);\n}\n\n[Test]\npublic void SortEmptyCollection()\n{\n List<int> emptyList = new();\n\n Assert.DoesNotThrow(() => emptyList.Sort(SortAlgorithm.Tim));\n Assert.AreEqual(0, emptyList.Count);\n}\nFrom /workspaces/com.wallstop-studios.unity-helpers/Tests/Runtime/DataStructures/QuadTree2DTests.cs:
[Test]\npublic void ConstructorWithEmptyCollectionSucceeds()\n{\n List<Vector2> points = new();\n QuadTree2D<Vector2> tree = CreateTree(points);\n Assert.IsNotNull(tree);\n\n List<Vector2> results = new();\n tree.GetElementsInRange(Vector2.zero, 10000f, results);\n Assert.AreEqual(0, results.Count);\n}\n\n[Test]\npublic void GetApproximateNearestNeighborsWithEmptyTreeReturnsEmpty()\n{\n List<Vector2> points = new();\n QuadTree2D<Vector2> tree = CreateTree(points);\n List<Vector2> results = new();\n\n tree.GetApproximateNearestNeighbors(Vector2.zero, 5, results);\n Assert.AreEqual(0, results.Count);\n}\n[Test]\npublic void IndexerThrowsOnInvalidIndex()\n{\n CyclicBuffer<int> buffer = new(5) { 1, 2 };\n\n Assert.Throws<IndexOutOfRangeException>(() => { _ = buffer[-1]; });\n Assert.Throws<IndexOutOfRangeException>(() => { _ = buffer[2]; });\n Assert.Throws<IndexOutOfRangeException>(() => { _ = buffer[int.MaxValue]; });\n Assert.Throws<IndexOutOfRangeException>(() => { _ = buffer[int.MinValue]; });\n}\nFrom /workspaces/com.wallstop-studios.unity-helpers/Tests/Runtime/DataStructures/CyclicBufferTests.cs:
[Test]\npublic void IndexerGetOutOfBounds()\n{\n CyclicBuffer<int> buffer = new(5) { 1, 2 };\n\n Assert.Throws<IndexOutOfRangeException>(() =>\n {\n _ = buffer[-1];\n });\n Assert.Throws<IndexOutOfRangeException>(() =>\n {\n _ = buffer[2];\n });\n Assert.Throws<IndexOutOfRangeException>(() =>\n {\n _ = buffer[5];\n });\n Assert.Throws<IndexOutOfRangeException>(() =>\n {\n _ = buffer[int.MaxValue];\n });\n Assert.Throws<IndexOutOfRangeException>(() =>\n {\n _ = buffer[int.MinValue];\n });\n}\n[Test]\npublic void AccessAfterDisposeThrows()\n{\n Cache<int, int> cache = CacheBuilder<int, int>\n .NewBuilder()\n .MaximumSize(100)\n .Build();\n\n cache.Dispose();\n\n Assert.Throws<ObjectDisposedException>(() => cache.Set(1, 1));\n Assert.Throws<ObjectDisposedException>(() => cache.TryGet(1, out _));\n}\n[Test]\npublic void IntMaxCapacityOk()\n{\n CyclicBuffer<int> buffer = new(int.MaxValue);\n CollectionAssert.AreEquivalent(Array.Empty<int>(), buffer);\n\n const int tries = 50;\n List<int> expected = new(tries);\n for (int i = 0; i < tries; ++i)\n {\n buffer.Add(i);\n expected.Add(i);\n CollectionAssert.AreEquivalent(expected, buffer);\n }\n}\nif (x == null) or try-catch suggests a potential \"impossible\" statedefault cases indicate unhandled enum valuesAlways include these categories in your tests:
Category Examples Normal cases Typical usage, common inputs Edge cases Empty, single element, boundary values Negative cases Invalid inputs, error conditions Extreme cases Maximum values, large collections \"The Impossible\" Destroyed objects, invalid enums, corrupted data"},{"location":"contributing/testing-patterns/#unh-suppress-usage","title":"UNH-SUPPRESS Usage","text":"When testing destroyed object behavior, use the // UNH-SUPPRESS comment:
// UNH-SUPPRESS tells the test linter this DestroyImmediate is intentional\nObject.DestroyImmediate(target); // UNH-SUPPRESS: Test verifies behavior after destruction\nOnly use this for intentional destruction testing, not for cleanup. Use Track() for normal test cleanup.
Choose assertions based on expected behavior:
C#// When graceful handling is expected\nAssert.DoesNotThrow(() => Process(invalidInput));\nAssert.IsNotEmpty(invalidValue.ToDisplayName());\nAssert.IsTrue(result == null);\n\n// When exceptions are expected\nAssert.Throws<InvalidEnumArgumentException>(() => Serialize(msg, (SerializationType)999));\nAssert.Throws<SerializationException>(() => Deserialize(corruptedData));\n\n// When default values are expected\nAssert.AreEqual(default(T), result);\nAssert.AreEqual(0, deserializedFromEmpty.Id);\nUse [TestCaseSource] to systematically cover impossible states:
private static IEnumerable<TestCaseData> ImpossibleStateTestCases()\n{\n // Destroyed references\n yield return new TestCaseData(CreateDestroyedObject())\n .SetName(\"State.DestroyedObject.HandledGracefully\");\n\n // Invalid enums\n yield return new TestCaseData((MyEnum)(-1))\n .SetName(\"State.NegativeEnumValue.HandledGracefully\");\n yield return new TestCaseData((MyEnum)999)\n .SetName(\"State.LargeEnumValue.HandledGracefully\");\n yield return new TestCaseData((MyEnum)int.MaxValue)\n .SetName(\"State.MaxIntEnumValue.HandledGracefully\");\n\n // Overflow values\n yield return new TestCaseData(int.MaxValue)\n .SetName(\"State.IntMaxValue.HandledGracefully\");\n yield return new TestCaseData(int.MinValue)\n .SetName(\"State.IntMinValue.HandledGracefully\");\n\n // Corrupted strings\n yield return new TestCaseData(\"\\0\\0\\0\")\n .SetName(\"State.NullChars.HandledGracefully\");\n yield return new TestCaseData(new string('\\uD800', 1000))\n .SetName(\"State.InvalidSurrogates.HandledGracefully\");\n}\n\n[Test]\n[TestCaseSource(nameof(ImpossibleStateTestCases))]\npublic void ProcessHandlesImpossibleStates(object input)\n{\n Assert.DoesNotThrow(() => Process(input));\n}\nTesting \"impossible\" states is essential for robust production code. These tests:
When adding new features, always ask: \"What happens if this input is destroyed, null, invalid, or corrupted?\" Then write tests to answer that question.
For more information on contributing to Unity Helpers, see the Contributing guide.
"},{"location":"features/editor-tools/asset-change-detection/","title":"Asset Change Detection","text":"Automatically respond to asset creation and deletion events.
The [DetectAssetChanged] attribute allows you to annotate methods that should execute automatically when specific asset types are created or deleted in the Unity Editor. Perfect for cache invalidation, autoconfiguration, validation, and maintaining derived data.
using System.Collections.Generic;\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\nusing WallstopStudios.UnityHelpers.Core.Extension;\n\npublic class SpriteCache : ScriptableObject\n{\n private static readonly HashSet<string> TrackedSpritePaths = new();\n\n [DetectAssetChanged(\n typeof(Sprite),\n AssetChangeFlags.Created | AssetChangeFlags.Deleted\n )]\n private static void OnSpriteChanged(AssetChangeContext context)\n {\n foreach (string path in context.CreatedAssetPaths)\n {\n TrackedSpritePaths.Add(path);\n Debug.Log($\"New sprite added: {path}\");\n }\n\n foreach (string path in context.DeletedAssetPaths)\n {\n TrackedSpritePaths.Remove(path);\n Debug.Log($\"Sprite removed: {path}\");\n }\n }\n}\nVisual Reference
Automatic method invocation when assets are created or deleted
"},{"location":"features/editor-tools/asset-change-detection/#attribute-parameters","title":"Attribute Parameters","text":"C#[DetectAssetChanged(\n Type assetType, // Type of asset to monitor (required)\n AssetChangeFlags flags, // Created, Deleted, or both (required)\n DetectAssetChangedOptions options = None // IncludeAssignableTypes for inheritance\n)]\n[Flags]\npublic enum AssetChangeFlags\n{\n None = 0,\n Created = 1 << 0, // Trigger on asset creation\n Deleted = 1 << 1, // Trigger on asset deletion\n}\n[Flags]\npublic enum DetectAssetChangedOptions\n{\n None = 0,\n IncludeAssignableTypes = 1 << 0, // Also trigger for derived types\n SearchPrefabs = 1 << 1, // Search prefabs for MonoBehaviour handlers\n SearchSceneObjects = 1 << 2, // Search open scenes for MonoBehaviour handlers\n}\nImportant: SearchPrefabs and SearchSceneObjects are only applicable to instance methods on MonoBehaviour classes. Static methods work without these options.
The attribute supports three method signatures:
"},{"location":"features/editor-tools/asset-change-detection/#1-no-parameters-fire-and-forget","title":"1. No Parameters (Fire-and-Forget)","text":"C#[DetectAssetChanged(typeof(ScriptableObject), AssetChangeFlags.Created)]\nprivate static void OnScriptableObjectCreated()\n{\n Debug.Log(\"A ScriptableObject was created - invalidate cache\");\n}\nWhen to use: Simple cache invalidation that doesn't need asset details
"},{"location":"features/editor-tools/asset-change-detection/#2-full-context-recommended","title":"2. Full Context (Recommended)","text":"C#[DetectAssetChanged(typeof(AudioClip), AssetChangeFlags.Created | AssetChangeFlags.Deleted)]\nprivate static void OnAudioClipChanged(AssetChangeContext context)\n{\n Debug.Log($\"AudioClip change: {context.Flags}\");\n\n foreach (string path in context.CreatedAssetPaths)\n {\n AudioClip clip = AssetDatabase.LoadAssetAtPath<AudioClip>(path);\n ProcessAudioClip(clip);\n }\n\n foreach (string path in context.DeletedAssetPaths)\n {\n Debug.Log($\"AudioClip deleted: {path}\");\n }\n}\nWhen to use: Need to handle both creation and deletion, or need access to all changed paths
"},{"location":"features/editor-tools/asset-change-detection/#3-typed-arrays-advanced","title":"3. Typed Arrays (Advanced)","text":"C#[DetectAssetChanged(typeof(Material), AssetChangeFlags.Created | AssetChangeFlags.Deleted)]\nprivate static void OnMaterialChanged(Material[] createdMaterials, string[] deletedPaths)\n{\n foreach (Material mat in createdMaterials)\n {\n Debug.Log($\"Material created: {mat.name}\");\n ValidateMaterial(mat);\n }\n\n foreach (string path in deletedPaths)\n {\n Debug.Log($\"Material deleted: {path}\");\n }\n}\nWhen to use: Need strongly-typed access to created assets; deleted assets are always paths since the asset no longer exists
"},{"location":"features/editor-tools/asset-change-detection/#inheritance-support","title":"Inheritance Support","text":"By default, the attribute only triggers for exact type matches. Use IncludeAssignableTypes to include derived types:
// Triggers for ScriptableObject and ALL derived types\n[DetectAssetChanged(\n typeof(ScriptableObject),\n AssetChangeFlags.Created,\n DetectAssetChangedOptions.IncludeAssignableTypes\n)]\nprivate static void OnAnyScriptableObjectCreated(ScriptableObject obj)\n{\n Debug.Log($\"ScriptableObject created: {obj.GetType().Name}\");\n}\n\n// Only triggers for exact Material type (not derived classes)\n[DetectAssetChanged(typeof(Material), AssetChangeFlags.Created)]\nprivate static void OnExactMaterialCreated(Material mat)\n{\n Debug.Log(\"Material (exact type) created\");\n}\nThe AssetChangeContext class provides complete information about the change:
public sealed class AssetChangeContext\n{\n public Type AssetType { get; } // The type being watched\n public AssetChangeFlags Flags { get; } // Created, Deleted, or both\n public IReadOnlyList<string> CreatedAssetPaths { get; } // Paths of created assets\n public IReadOnlyList<string> DeletedAssetPaths { get; } // Paths of deleted assets\n public bool HasCreatedAssets { get; } // True if any created\n public bool HasDeletedAssets { get; } // True if any deleted\n}\nEditorApplication.delayCall// \u2705 GOOD: Static method for global cache\n[DetectAssetChanged(typeof(Sprite), AssetChangeFlags.Created | AssetChangeFlags.Deleted)]\nprivate static void OnSpriteChanged()\n{\n SpriteManager.InvalidateCache();\n}\n\n// \u2705 GOOD: Instance method for component-specific logic\n[DetectAssetChanged(typeof(AudioClip), AssetChangeFlags.Created)]\nprivate void OnAudioClipCreated(AudioClip clip)\n{\n if (clip.name.StartsWith(audioPrefix))\n {\n RegisterClip(clip);\n }\n}\n\n// \u26a0\ufe0f CAUTION: Expensive operation during import\n[DetectAssetChanged(typeof(Texture2D), AssetChangeFlags.Created)]\nprivate static void OnTextureCreated(Texture2D texture)\n{\n // Heavy processing - consider deferring\n ProcessTexture(texture);\n}\n[DetectAssetChanged(typeof(Material), AssetChangeFlags.Created)]\nprivate static void OnMaterialCreated(string assetPath)\n{\n // \u274c BAD: Creating assets during asset processing can cause loops\n // AssetDatabase.CreateAsset(newMaterial, \"Assets/Generated.mat\");\n\n // \u2705 GOOD: Defer asset creation\n EditorApplication.delayCall += () =>\n {\n AssetDatabase.CreateAsset(newMaterial, \"Assets/Generated.mat\");\n };\n}\npublic class TextureAtlas : ScriptableObject\n{\n private static List<Texture2D> _cachedTextures;\n\n [DetectAssetChanged(typeof(Texture2D), AssetChangeFlags.Created | AssetChangeFlags.Deleted)]\n private static void OnTextureChanged()\n {\n _cachedTextures = null; // Invalidate cache\n }\n}\npublic class MaterialValidator : ScriptableObject\n{\n [DetectAssetChanged(typeof(Material), AssetChangeFlags.Created)]\n private static void ValidateNewMaterials(Material[] createdMaterials, string[] deletedPaths)\n {\n foreach (Material material in createdMaterials)\n {\n if (material.shader.name == \"Standard\")\n {\n // Apply project-wide defaults\n material.SetFloat(\"_Metallic\", 0.0f);\n material.SetFloat(\"_Glossiness\", 0.5f);\n EditorUtility.SetDirty(material);\n }\n }\n }\n}\npublic abstract class GameData : ScriptableObject { }\n\npublic class DataRegistry : ScriptableObject\n{\n private static readonly HashSet<string> RegisteredPaths = new();\n\n [DetectAssetChanged(\n typeof(GameData),\n AssetChangeFlags.Created | AssetChangeFlags.Deleted,\n DetectAssetChangedOptions.IncludeAssignableTypes\n )]\n private static void OnGameDataChanged(GameData[] created, string[] deletedPaths)\n {\n foreach (GameData data in created)\n {\n string path = AssetDatabase.GetAssetPath(data);\n RegisteredPaths.Add(path);\n Debug.Log($\"Registered: {data.GetType().Name} at {path}\");\n }\n\n foreach (string path in deletedPaths)\n {\n RegisteredPaths.Remove(path);\n Debug.Log($\"Unregistered: {path}\");\n }\n }\n}\nUse SearchPrefabs to invoke instance methods on MonoBehaviours attached to prefabs:
public class SpriteCache : MonoBehaviour\n{\n [SerializeField] private List<Sprite> _cachedSprites = new();\n\n [DetectAssetChanged(\n typeof(Sprite),\n AssetChangeFlags.Created | AssetChangeFlags.Deleted,\n DetectAssetChangedOptions.SearchPrefabs\n )]\n private void OnSpriteChanged(AssetChangeContext context)\n {\n // This instance method is called on the prefab asset\n Debug.Log($\"SpriteCache on prefab received sprite change: {context.Flags}\");\n RefreshCache();\n }\n\n private void RefreshCache()\n {\n _cachedSprites.Clear();\n // Rebuild cache...\n }\n}\nWhen to use: When your MonoBehaviour needs instance-specific state or serialized fields
"},{"location":"features/editor-tools/asset-change-detection/#scene-object-instance-methods","title":"Scene Object Instance Methods","text":"Use SearchSceneObjects to invoke instance methods on MonoBehaviours in open scenes:
public class LiveAssetWatcher : MonoBehaviour\n{\n [SerializeField] private string _watchedFolder;\n\n [DetectAssetChanged(\n typeof(Texture2D),\n AssetChangeFlags.Created,\n DetectAssetChangedOptions.SearchSceneObjects\n )]\n private void OnTextureCreated(AssetChangeContext context)\n {\n // Called on every LiveAssetWatcher instance in all open scenes\n foreach (string path in context.CreatedAssetPaths)\n {\n if (path.StartsWith(_watchedFolder))\n {\n Debug.Log($\"{name} detected new texture: {path}\");\n HandleNewTexture(path);\n }\n }\n }\n\n private void HandleNewTexture(string path) { /* ... */ }\n}\nWhen to use: For editor tools that need to react to changes based on scene-specific configuration
"},{"location":"features/editor-tools/asset-change-detection/#combined-prefab-and-scene-search","title":"Combined Prefab and Scene Search","text":"Use both options together to find handlers in both prefabs and open scenes:
C#public class UniversalAssetHandler : MonoBehaviour\n{\n [DetectAssetChanged(\n typeof(AudioClip),\n AssetChangeFlags.Created | AssetChangeFlags.Deleted,\n DetectAssetChangedOptions.SearchPrefabs | DetectAssetChangedOptions.SearchSceneObjects\n )]\n private void OnAudioClipChanged(AssetChangeContext context)\n {\n // Called on instances in both prefabs AND scene objects\n Debug.Log($\"{name} (on {gameObject.name}) received audio change\");\n }\n}\nPerformance Note: Searching prefabs and scenes has overhead. Use these options only when you need instance-specific behavior. For simple notifications, prefer static methods.
"},{"location":"features/editor-tools/asset-change-detection/#implementation-details","title":"Implementation Details","text":"The DetectAssetChangeProcessor (Editor assembly) automatically:
[DetectAssetChanged]AssetPostprocessorThreading: All callbacks execute on the main thread during asset processing
Timing: Methods are called after Unity completes asset import/deletion
"},{"location":"features/editor-tools/asset-change-detection/#troubleshooting","title":"Troubleshooting","text":""},{"location":"features/editor-tools/asset-change-detection/#method-is-not-called","title":"Method Is Not Called","text":"IncludeAssignableTypes)SearchPrefabs if the handler is on a prefab assetSearchSceneObjects if the handler is on a GameObject in a sceneIf your instance method on a MonoBehaviour isn't being called:
DetectAssetChangedOptions.SearchPrefabsDetectAssetChangedOptions.SearchSceneObjectsSearchPrefabs | SearchSceneObjectsstatic method instead (most efficient)EditorApplication.delayCallstatic methods to avoid unnecessary instance lookupsSearchPrefabs in large projects - it loads all prefabs to check for componentsSearchSceneObjects with many open scenes - searches all loaded scenesnull for deletion eventsAssetChangeFlags.DeletedComprehensive documentation for all editor wizards, windows, and automation tools.
"},{"location":"features/editor-tools/editor-tools-guide/#what-do-you-want-to-do-task-based-index","title":"What Do You Want To Do? (Task-Based Index)","text":""},{"location":"features/editor-tools/editor-tools-guide/#optimize-sprite-memory-performance","title":"Optimize Sprite Memory & Performance","text":"See the Inspector Attributes documentation for:
[WInLineEditor] \u2014 Embed nested object inspectors inline[WShowIf] \u2014 Conditional field visibility[WEnumToggleButtons] \u2014 Visual toggle buttons for enums[WValueDropDown], [IntDropDown], [StringInList] \u2014 Selection dropdowns[WReadOnly], [WNotNull] \u2014 Validation attributes[WGroup], [WButton] \u2014 Layout and method invocationMenu: Tools > Wallstop Studios > Unity Helpers > Image Blur
Purpose: Apply Gaussian blur effects to textures in batch for backgrounds, depth-of-field, or softened sprites.
Key Features:
Common Workflow:
Text Only1. Open Image Blur Tool\n2. Drag sprite folder into designated area\n3. Set blur radius (e.g., 10 for subtle, 50 for heavy)\n4. Click \"Apply Blur\"\n5. Find blurred versions with \"_blurred_[radius]\" suffix\nBest For:
Visual Demo
Adjusting blur radius from 0 to 200 pixels on a UI background texture
"},{"location":"features/editor-tools/editor-tools-guide/#sprite-cropper","title":"Sprite Cropper","text":"Menu: Tools > Wallstop Studios > Unity Helpers > Sprite Cropper
Purpose: Automatically remove transparent padding from sprites to optimize memory and atlas packing.
Key Features:
Common Workflow:
Text Only1. Open Sprite Cropper\n2. Add sprite directories to \"Input Directories\"\n3. Set padding (e.g., 2px on all sides for outlines)\n4. Enable \"Only Necessary\" to skip already-cropped sprites\n5. Click \"Find Sprites To Process\" to preview\n6. Click \"Process X Sprites\"\n7. Replace originals with \"Cropped_*\" versions\n\n**Danger Zone \u2014 Reference Replacement:**\n- After cropping into `Cropped_*` outputs, you can optionally replace references to original sprites across assets with their cropped counterparts. This is powerful but destructive; review the preview output and ensure you have version control backups before applying.\nBest For:
Performance Impact: Can reduce texture memory by 30-70% on padded sprites.
Visual Demo
Before and after: transparent padding removed while preserving sprite content and pivot
Related Tools:
Menu: Tools > Wallstop Studios > Unity Helpers > Texture Settings Applier
Purpose: Batch apply standardized texture import settings across multiple assets.
Configurable Settings:
Common Configurations:
UI Sprites (Pixel-Perfect):
Text OnlyFilter Mode: Point\nWrap Mode: Clamp\nCompression: CompressedHQ or None\nGenerate Mip Maps: false\nMax Size: 2048 or match source\nEnvironment Textures:
Text OnlyFilter Mode: Trilinear\nWrap Mode: Repeat\nCompression: CompressedHQ\nGenerate Mip Maps: true\nCrunch Compression: true\nCharacter Sprites:
Text OnlyFilter Mode: Bilinear\nWrap Mode: Clamp\nCompression: CompressedHQ\nGenerate Mip Maps: false\nWorkflow:
Text Only1. Open Texture Settings Applier\n2. Configure desired settings with checkboxes\n3. Add textures individually OR add directories\n4. Click \"Set\" to apply\n5. Unity reimports affected textures\nBest For:
Visual Reference
Texture Settings Applier with filter mode, wrap mode, and compression options
Related Tools:
Menu: Tools > Wallstop Studios > Unity Helpers > Sprite Pivot Adjuster
Purpose: Compute and apply alpha\u2011weighted center\u2011of\u2011mass pivots in bulk. Produces perceptually centered pivots (ignoring near\u2011transparent pixels) and speeds re\u2011imports by skipping unchanged results.
Key Features:
Workflow:
Text Only1) Open Sprite Pivot Adjuster\n2) Add one or more directories\n3) (Optional) Set Sprite Name Regex to filter\n4) Adjust Alpha Cutoff (e.g., 0.01 to ignore fringe pixels)\n5) Enable \u201cSkip Unchanged\u201d to reimport only when pivot changes\n6) (Optional) Enable \u201cForce Reimport\u201d to override skip\n7) Run the adjuster to write importer pivot values\nBest For:
Visual Reference
Sprite Pivot Adjuster with alpha cutoff slider and directory selection
"},{"location":"features/editor-tools/editor-tools-guide/#sprite-settings-applier","title":"Sprite Settings Applier","text":"Menu: Tools > Wallstop Studios > Unity Helpers > Sprite Settings Applier
Purpose: Apply sprite\u2011specific importer settings in bulk, driven by matchable \u201cprofiles\u201d (Any/NameContains/PathContains/Regex/Extension) with priorities. Great for standardizing PPU, pivots, modes, and compression rules across large folders.
Profiles & Matching:
SpriteSettingsProfileCollection ScriptableObjectKey Settings (per profile):
Workflow:
Text Only1) Create a SpriteSettingsProfileCollection (Assets > Create > \u2026 if available) or configure profiles in the window\n2) Open Sprite Settings Applier\n3) Add directories and/or explicit sprites\n4) Choose which profile(s) to apply and click Set\n5) Unity reimports affected sprites\nBest For:
Visual Reference
Sprite Settings Applier with profile matching modes and import settings
"},{"location":"features/editor-tools/editor-tools-guide/#texture-resizer","title":"Texture Resizer","text":"Menu: Tools > Wallstop Studios > Unity Helpers > Texture Resizer
Purpose: Batch resize textures using bilinear or point filtering algorithms with configurable scaling multipliers.
Configuration Options:
How It Works:
extraWidth = width / (PPU * widthMultiplier)newSize = (width + extraWidth, height + extraHeight)numResizes iterationsWorkflow:
Text Only1. Open Texture Resizer wizard\n2. Add textures manually OR drag texture folders\n3. Set algorithm (Bilinear for smooth, Point for pixel art)\n4. Configure PPU and multipliers\n5. Set number of resize passes\n6. Click \"Resize\" to apply\nResize Algorithms:
Bilinear:
Point:
Best For:
Important Notes:
Visual Reference
Texture Resizer with bilinear/point algorithm selection and multiplier settings
"},{"location":"features/editor-tools/editor-tools-guide/#fit-texture-size","title":"Fit Texture Size","text":"Menu: Tools > Wallstop Studios > Unity Helpers > Fit Texture Size
Purpose: Automatically adjust texture max size import settings to match actual source dimensions (power-of-two).
Key Features:
Fit Modes:
GrowAndShrink:
GrowOnly:
ShrinkOnly:
Workflow:
Text Only1. Open Fit Texture Size\n2. Select Fit Mode (GrowAndShrink/GrowOnly/ShrinkOnly)\n3. Add texture folders to process\n4. Click \"Calculate Potential Changes\" to preview\n5. Review how many textures will be modified\n6. Click \"Run Fit Texture Size\" to apply\nExample:
Text OnlySource Texture: 1920x1080 pixels\nCurrent Max Size: 512\nFit Mode: GrowAndShrink\nResult: Max Size \u2192 2048 (fits source dimensions)\n\nSource Texture: 64x64 pixels\nCurrent Max Size: 2048\nFit Mode: ShrinkOnly\nResult: Max Size \u2192 64 (matches source)\nAlgorithm:
size = max(width, height)Best For:
Performance:
Visual Reference
Fit Texture Size with GrowAndShrink/GrowOnly/ShrinkOnly mode selection
"},{"location":"features/editor-tools/editor-tools-guide/#animation-tools","title":"Animation Tools","text":""},{"location":"features/editor-tools/editor-tools-guide/#sprite-animation-editor-animation-viewer-window","title":"Sprite Animation Editor (Animation Viewer Window)","text":"Menu: Tools > Wallstop Studios > Unity Helpers > Sprite Animation Editor
Purpose: Visual editor for 2D sprite animations with real-time preview and frame manipulation.
Key Features:
Typical Workflow:
Text Only1. Open Sprite Animation Editor\n2. Click \"Browse Clips (Multi)...\" to select animations\n3. Click a loaded clip in left panel to edit\n4. Drag frames in \"Frames\" panel to reorder\n5. Adjust FPS field and click \"Apply FPS\"\n6. Preview updates in real-time\n7. Click \"Save Clip\" to write changes\nExample Session:
Text Only// Edit walk cycle animation:\n1. Load \"PlayerWalk.anim\"\n2. Preview plays at original 12 FPS\n3. Drag frame 3 to position 1 (change starting pose)\n4. Change FPS to 10 for slower walk\n5. Click \"Apply FPS\" to preview\n6. Click \"Save Clip\" to finalize\nBest For:
Tips:
Visual Demo
Drag-and-drop frame reordering with real-time preview updates
Adjusting FPS slider and seeing immediate preview speed change
"},{"location":"features/editor-tools/editor-tools-guide/#animation-creator","title":"Animation Creator","text":"Menu: Tools > Wallstop Studios > Unity Helpers > Animation Creator
Purpose: Bulk\u2011create AnimationClips from sprite naming patterns \u2014 one\u2011click generation from folders of sprites. Eliminates manual clip setup and ensures consistent naming, ordering, and FPS/loop settings.
Problems Solved:
Key Features:
spriteNameRegex)(?<base>)(?<index>)Framerate Modes:
Mode DescriptionConstant Fixed frames per second (default) Curve AnimationCurve-based timing for per-frame speed variation Common Naming Patterns (auto\u2011detected):
Text OnlyPlayer_Idle_0.png, Player_Idle_1.png, ... // base: Player_Idle, index: 0..N\nslime-walk-01.png, slime-walk-02.png // base: slime-walk, index: 1..N\nMage/Attack (0).png, Mage/Attack (1).png // base: Mage_Attack, index: 0..N (folder prefix optional)\nCustom Group Regex Examples:
Text Only// Named groups are optional but powerful when needed\n^(?<base>.*?)(?:_|\\s|-)?(?<index>\\d+)\\.[Pp][Nn][Gg]$ // base + trailing digits\n^Enemy_(?<base>Walk)_(?<index>\\d+)$ // narrow to specific clip type\nHow To Use (one\u2011click flow):
Text Only1) Open Animation Creator\n2) Add one or more source folders\n3) (Optional) Set sprite filter regex to narrow matches\n4) Click \u201cAuto\u2011Parse Matched Sprites into Animations\u201d\n5) Review generated Animation Data (set FPS/loop per clip)\n6) Click \u201cCreate\u201d (Action button) to write .anim assets\nPreview & Safety:
1,10,11,2,\u2026 issuesTips:
Name_Action_###)Best For:
Visual Demo
One-click auto-parse: sprites grouped by naming pattern, clips generated instantly
Related Tools:
Menu: Tools > Wallstop Studios > Unity Helpers > Animation Copier
Purpose: Analyze, duplicate, and synchronize AnimationClips between source and destination folders with previews, dry\u2011runs, and cleanup actions.
What It Analyzes:
Workflow:
Text Only1) Open Animation Copier\n2) Select Source Path (e.g., Assets/Sprites/Animations)\n3) Select Destination Path (e.g., Assets/Animations)\n4) Click \u201cAnalyze Source & Destination\u201d\n5) Review New/Changed/Unchanged/Orphans tabs (filter/sort)\n6) Choose a copy mode:\n - Copy New / Copy Changed / Copy All (optional force replace)\n7) (Optional) Dry Run to preview without writing\n8) Use Cleanup:\n - Delete Unchanged Source Duplicates\n - Delete Destination Orphans\nSafety & Options:
Best For:
Visual Reference
Animation Copier with new/changed/unchanged/orphan tabs and copy actions
"},{"location":"features/editor-tools/editor-tools-guide/#sprite-sheet-animation-creator","title":"Sprite Sheet Animation Creator","text":"Menu: Tools > Wallstop Studios > Unity Helpers > Sprite Sheet Animation Creator
Purpose: Turn a sliced sprite sheet into one or more AnimationClips with live preview, drag\u2011to\u2011select sprite ranges, and per\u2011clip FPS/loop/cycle offset.
Key Features:
Usage:
Text Only1) Open Sprite Sheet Animation Creator\n2) Drag a sliced Texture2D (or use the object field)\n3) Select frames (drag across thumbnails) to define a clip\n4) Name the clip, set FPS/curve, loop, cycle offset\n5) Repeat to add multiple definitions\n6) Click \u201cGenerate Animations\u201d and choose output folder\nBest For:
Visual Demo
Drag-select frame ranges on sprite sheet thumbnails with instant preview playback
"},{"location":"features/editor-tools/editor-tools-guide/#sprite-sheet-extractor","title":"Sprite Sheet Extractor","text":"Menu: Tools > Wallstop Studios > Unity Helpers > Sprite Sheet Extractor
Purpose: Extract individual sprites from sprite sheet textures and save them as separate PNG files with batch processing, preview, and optional reference replacement.
Key Features:
Extraction Modes:
FromMetadata:
GridBased:
AlphaDetection:
PaddedGrid:
Pivot Modes:
Workflow:
Text Only1. Open Sprite Sheet Extractor\n2. Add input directories containing sprite sheets\n3. (Optional) Set sprite name regex filter\n4. Configure extraction mode and settings\n5. Click \"Discover Sprite Sheets\" to scan\n6. Review detected sheets and sprites in preview\n7. Adjust per-sheet settings if needed\n8. Set output directory\n9. Click \"Extract\" to generate individual sprites\n10. (Optional) Use reference replacement for prefab updates\nBest For:
Tips:
Menu: Tools > Wallstop Studios > Unity Helpers > AnimationEvent Editor
Purpose: Advanced visual editor for creating and managing animation events with sprite preview, method auto-discovery, and parameter editing.
Key Features:
[AnimationEvent] attributeWorkflow:
Text Only1. Open Animation Event Editor\n2. Drag Animator component into \"Animator Object\" field\n3. Select animation from dropdown (or use Animation Search)\n4. Set \"FrameIndex\" for new event\n5. Click \"Add Event\" to create event at that frame\n6. Configure event:\n a. Select TypeName (MonoBehaviour with event methods)\n b. Select MethodName from available methods\n c. Set parameters (int, float, string, object, enum)\n7. Reorder events if needed (Move Up/Down buttons)\n8. Click \"Save\" to write changes to animation clip\nModes:
Explicit Mode (Default):
[AnimationEvent] attributeNon-Explicit Mode:
Control Frame Time:
Sprite Preview:
Event Management:
Adding Events:
Editing Events:
Reordering:
Resetting:
Parameter Types Supported:
int - IntField editorfloat - FloatField editorstring - TextField editorUnityEngine.Object - ObjectField editorEnum - Dropdown with an override optionBest For:
Tips:
Common Method Signatures:
C#using WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class CharacterAnimationEvents : MonoBehaviour\n{\n [AnimationEvent] // Shows in Explicit Mode\n public void PlayFootstep() { }\n\n [AnimationEvent]\n public void SpawnEffect(string effectName) { }\n\n [AnimationEvent]\n public void ApplyDamage(int damage) { }\n\n [AnimationEvent]\n public void SetAnimationState(CharacterState state) { } // Enum parameter\n}\nMenu: Tools > Wallstop Studios > Unity Helpers > Sprite Atlas Generator
Purpose: Comprehensive tool for creating and managing Unity Sprite Atlases with regex-based sprite selection, label filtering, and automated packing.
Key Features:
Configuration Asset: Create configurations via Assets > Create > Wallstop Studios > Unity Helpers > Scriptable Sprite Atlas Config
ScriptableSpriteAtlas Configuration:
Text OnlySprite Sources:\n- spritesToPack: Manually added sprites (always included)\n- sourceFolderEntries: Define folders with regex/label filters\n\nSource Folder Entry Options:\n- folderPath: Folder to scan (relative to Assets/)\n- selectionMode: Regex | Labels | Both\n- regexes: List of regex patterns (all must match - AND logic)\n- regexAndTagLogic: How to combine regex and labels (And/Or)\n- labelSelectionMode: All | AnyOf\n- labels: Asset labels to filter by\n\nOutput Atlas Settings:\n- outputSpriteAtlasDirectory: Where to save .spriteatlas\n- outputSpriteAtlasName: Name of atlas file\n\nPacking Settings:\n- maxTextureSize: 32-16384 (power of 2)\n- enableRotation: Allow sprite rotation for better packing\n- padding: Pixels between sprites (0-32)\n- enableTightPacking: Optimize packing density\n- enableAlphaDilation: Dilate alpha edges\n- readWriteEnabled: Enable Read/Write on atlas texture\n\nCompression Settings:\n- useCrunchCompression: Enable crunch compression\n- crunchCompressionLevel: 0-100 quality\n- compression: Compressed/CompressedHQ/Uncompressed\nTypical Workflow:
Text Only1. Open Sprite Atlas Generator\n2. Click \"Create New Config in 'Assets/Data'\"\n3. Configure the new atlas:\n a. Set output name and directory\n b. Click \"Add New Source Folder Entry\"\n c. Select folder containing sprites\n d. Add regex patterns (e.g., \"^character_.*\\\\.png$\")\n e. Or/and add labels for filtering\n f. Configure packing settings (texture size, padding, etc.)\n4. Click \"Scan Folders for '[config name]'\"\n5. Review sprites to add/remove\n6. Click \"Add X Sprites\" to populate the list\n7. Click \"Generate/Update '[atlas name].spriteatlas' ONLY\"\n8. Click \"Pack All Generated Sprite Atlases\" to pack textures\nExample Configurations:
Character Sprites Atlas:
Text OnlyfolderPath: Assets/Sprites/Characters\nselectionMode: Regex\nregexes: [\"^player_.*\\\\.png$\", \".*_idle_.*\"]\nmaxTextureSize: 2048\npadding: 4\ncompression: CompressedHQ\nUI Icons by Label:
Text OnlyfolderPath: Assets/Sprites/UI\nselectionMode: Labels\nlabelSelectionMode: AnyOf\nlabels: [\"icon\", \"ui\"]\nmaxTextureSize: 1024\npadding: 2\nCombined Regex + Labels:
Text OnlyfolderPath: Assets/Sprites/Effects\nselectionMode: Regex | Labels\nregexes: [\"^vfx_.*\"]\nlabels: [\"particle\"]\nregexAndTagLogic: And\nmaxTextureSize: 2048\nAdvanced Features:
Scan and Preview:
Source Sprite Utilities:
Batch Operations:
Best For:
Tips:
Common Issues:
Visual Reference
Sprite Atlas Generator with regex-based sprite selection and packing settings
Scanning folders and previewing which sprites will be added to the atlas
"},{"location":"features/editor-tools/editor-tools-guide/#validation-quality-tools","title":"Validation & Quality Tools","text":""},{"location":"features/editor-tools/editor-tools-guide/#prefab-checker","title":"Prefab Checker","text":"
Menu: Tools > Wallstop Studios > Unity Helpers > Prefab Checker
Purpose: Comprehensive prefab validation to detect configuration issues before runtime.
Validation Checks:
Check Description Severity Missing Scripts Detects broken MonoBehaviour references Critical Nulls in Lists/Arrays Finds null elements in serialized collections High Missing Required Components Validates [RequireComponent] dependencies Critical Empty String Fields Identifies unset string fields Medium Null Object References Finds unassigned UnityEngine.Object fields High Only if [ValidateAssignment] Restricts null checks to annotated fields Configurable Disabled Root GameObject Flags inactive prefab roots Medium Disabled Components Reports disabled Behaviour components LowTypical Validation Workflow:
Text Only// Before committing prefab changes:\n1. Open Prefab Checker\n2. Enable relevant checks (especially Missing Scripts, Required Components)\n3. Add \"Assets/Prefabs\" folder\n4. Click \"Run Checks\"\n5. Review console output (click to select problematic prefabs)\n6. Fix reported issues\n7. Re-run checks to verify\n8. Commit changes\nCI/CD Integration:
Text Only// Can be scripted for automated builds\n- Run validation on changed prefab folders\n- Parse console output for errors\n- Fail build if critical issues found\nBest Practices:
[ValidateAssignment] attribute on critical fieldsPerformance: Uses cached reflection for fast repeated checks.
Best For:
Visual Reference
Prefab Checker with configurable validation checks and folder selection
Console output showing detected prefab issues with clickable links
"},{"location":"features/editor-tools/editor-tools-guide/#unity-method-analyzer","title":"Unity Method Analyzer","text":"Menu: Tools > Wallstop Studios > Unity Helpers > Unity Method Analyzer
Purpose: Detect inheritance issues and Unity lifecycle method errors across your entire C# codebase before they cause runtime bugs.
\ud83d\udcd6 Full Documentation: Unity Method Analyzer Guide
Key Features:
What It Detects:
Issue Type Example Missingoverride keyword Hiding base method instead of overriding Wrong Unity method signature OnCollisionEnter(Collider c) instead of OnCollisionEnter(Collision c) Shadowed lifecycle methods Both base and derived class have private void Start() Static lifecycle methods static void Awake() won't be called by Unity Quick Start:
Text Only1. Open Unity Method Analyzer\n2. Add source directories (e.g., Assets/Scripts)\n3. Click \"Analyze Code\"\n4. Review issues grouped by file, severity, or category\n5. Double-click to navigate to problematic code\n6. Export report for team review or CI/CD\nVisual Demo
The analyzer scanning a project and displaying categorized issues
Suppressing Warnings:
For test code or intentional patterns, use [SuppressAnalyzer]:
[SuppressAnalyzer(\"Test fixture for analyzer validation\")]\npublic class TestClassWithIntentionalIssues : BaseClass\n{\n public void HiddenMethod() { } // Won't trigger warning\n}\nBest For:
These custom inspectors enhance Unity components with additional functionality and convenience features.
"},{"location":"features/editor-tools/editor-tools-guide/#matchcollidertosprite-editor","title":"MatchColliderToSprite Editor","text":"Component: MatchColliderToSprite
Purpose: Provides a button in the inspector to manually trigger collider-to-sprite matching.
Features:
OnValidate() to update colliderWhen to Use:
Component: PolygonCollider2DOptimizer
Purpose: Custom inspector for optimizing PolygonCollider2D point counts with configurable tolerance.
Features:
How It Works:
Best For:
Tolerance Guide:
Component: EnhancedImage (extends Unity's Image)
Purpose: Extended inspector for EnhancedImage with HDR color support and shape mask configuration.
Additional Properties:
Features:
Material Detection:
Shaders/Materials/BackgroundMask-Material.matShape Mask:
_ShapeMask texture2D propertyHDR Color:
Best For:
Workflow:
Text Only1. Add EnhancedImage component to UI GameObject\n2. If yellow \"Fix Material\" button appears, click it\n3. Configure HDR Color for glow/intensity\n4. Assign Shape Mask texture if needed\n5. Shader must expose _ShapeMask property\nIcon Customization:
"},{"location":"features/editor-tools/editor-tools-guide/#property-drawers-attributes","title":"Property Drawers & Attributes","text":"
Custom property drawers enhance the inspector with conditional display, validation, and specialized input fields.
"},{"location":"features/editor-tools/editor-tools-guide/#winlineeditor-property-drawer","title":"WInLineEditor Property Drawer","text":"Attribute: [WInLineEditor]
Purpose: Embed the inspector for object references (ScriptableObjects, Materials, Components, Textures, etc.) directly below the field so you can edit configuration without losing context.
Modes (WInLineEditorMode):
AlwaysExpanded \u2014 always draws the inline inspector.FoldoutExpanded \u2014 shows a foldout that starts expanded.FoldoutCollapsed \u2014 shows a foldout that starts collapsed.Options: tune the presentation with constructor parameters:
inspectorHeight (default 200, min 160) \u2014 vertical space reserved for the inspector body.drawObjectField \u2014 hide or show the object picker next to the label.drawHeader \u2014 draw a bold header with a ping button (ping is shown only while a Project window tab is visible).drawPreview & previewHeight \u2014 render the preview area when the target editor exposes one.enableScrolling \u2014 wrap the inspector body in a scroll view for long inspectors.minInspectorWidth (default 520) \u2014 when the content area is narrower than this width, a horizontal scrollbar appears; set to 0 to disable the safeguard.WInLineEditor respects the Inline Editors defaults inside Unity Helpers Settings. Leave the mode argument unset to inherit the global foldout behaviour, or supply a WInLineEditorMode per field to override it. By default, Inline Editors start collapsed to mirror collapsible WGroups, so [WInLineEditor] without a mode expands only when you opt into a different setting.
Examples:
C#public class AbilityConfig : ScriptableObject\n{\n public string displayName;\n public float cooldown;\n}\n\npublic class AbilityDatabase : ScriptableObject\n{\n [WInLineEditor] public AbilityConfig defaultConfig;\n\n [WInLineEditor(\n WInLineEditorMode.FoldoutCollapsed,\n inspectorHeight: 180f,\n drawPreview: true,\n previewHeight: 64f)]\n public Texture2D abilityIcon;\n\n [WInLineEditor(\n WInLineEditorMode.AlwaysExpanded,\n inspectorHeight: 220f,\n drawObjectField: false,\n enableScrolling: false)]\n public AbilityConfig sharedTemplate;\n}\nFeatures:
HasPreviewGUI.Animation Settings:
Foldout animations are controlled via Unity Helpers Settings (Edit > Project Settings > Unity Helpers):
InlineEditorFoldoutTweenEnabled \u2014 Enable/disable smooth expand/collapse animations (default: true)InlineEditorFoldoutSpeed \u2014 Animation speed from 2.0 to 12.0 (default: 2.0)using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class AbilityConfig : ScriptableObject\n{\n public string abilityName;\n public Sprite icon;\n public float cooldown;\n}\n\npublic class WInLineEditorExample : MonoBehaviour\n{\n // Animation applies to foldout modes only\n [WInLineEditor(WInLineEditorMode.FoldoutCollapsed)] // Animated\n public AbilityConfig animatedFoldout;\n\n [WInLineEditor(WInLineEditorMode.AlwaysExpanded)] // No animation (always visible)\n public AbilityConfig alwaysVisible;\n}\nSee also: Inspector Settings Reference for complete settings documentation.
Visual Reference
WInLineEditor with embedded inspector for a ScriptableObject reference with foldout and collapse transitions
"},{"location":"features/editor-tools/editor-tools-guide/#wshowif-property-drawer","title":"WShowIf Property Drawer","text":"Attribute: [WShowIf]
Purpose: Conditionally show/hide fields in inspector based on boolean fields or enum values.
Syntax:
C#[WShowIf(nameof(fieldName))]\n[WShowIf(nameof(fieldName), inverse = true)]\n[WShowIf(nameof(fieldName), expectedValues: new object[] { value1, value2 })]\n[WShowIf(nameof(numericField), WShowIfComparison.GreaterThan, 10)]\n[WShowIf(nameof(stringField), WShowIfComparison.IsNotNullOrEmpty)]\n[WShowIf(nameof(parentField) + \".\" + nameof(ChildType.someFlag))]\nWShowIfComparison.Unknown exists only for backward compatibility and is marked obsolete; always choose an explicit comparison mode.
Examples:
Boolean Condition:
C#public bool enableFeature;\n\n[WShowIf(nameof(enableFeature))]\npublic float featureIntensity;\n\n[WShowIf(nameof(enableFeature), inverse = true)]\npublic string disabledMessage;\nEnum Condition:
C#public enum Mode { Simple, Advanced, Expert }\npublic Mode currentMode;\n\n[WShowIf(nameof(currentMode), expectedValues = new object[] { Mode.Advanced, Mode.Expert })]\npublic int advancedSetting;\nMultiple Values:
C#using System.Collections.Generic;\nusing UnityEngine;\nusing UnityEngine.Serialization;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\nusing WallstopStudios.UnityHelpers.Core.DataStructure.Adapters;\nusing WallstopStudios.UnityHelpers.Editor.Sprites;\n\npublic class SelectionModeExample : MonoBehaviour\n{\n public SpriteSelectionMode selectionMode;\n\n [WShowIf(\n nameof(selectionMode),\n expectedValues = new object[]\n {\n SpriteSelectionMode.Regex,\n SpriteSelectionMode.Regex | SpriteSelectionMode.Labels,\n }\n )]\n public List<string> regexPatterns;\n\n [FormerlySerializedAs(\"regexPatterns\")]\n [WShowIf(\n nameof(selectionMode),\n expectedValues = new object[]\n {\n SpriteSelectionMode.Regex,\n SpriteSelectionMode.Regex | SpriteSelectionMode.Labels,\n }\n )]\n public SerializableHashSet<string> regexPatterns1;\n\n [WShowIf(\n nameof(selectionMode),\n expectedValues = new object[]\n {\n SpriteSelectionMode.Regex,\n SpriteSelectionMode.Regex | SpriteSelectionMode.Labels,\n }\n )]\n public SerializableDictionary<int, string> regexPatterns2;\n\n public bool someOtherField;\n}\nFeatures:
IComparable/IComparable<T> type, null, and string/collection comparisonsinverse parameter inverts any comparison resultexpectedValues (or params arguments) for equality checks without manual arraysBest For:
Visual Reference
Field appears/disappears based on enum toggle state
"},{"location":"features/editor-tools/editor-tools-guide/#stringinlist-property-drawer","title":"StringInList Property Drawer","text":"Attribute: [StringInList]
Purpose: Display string or int fields as dropdown with predefined options.
Syntax:
C#// Static array\n[StringInList(\"Option1\", \"Option2\", \"Option3\")]\npublic string selectedOption;\n\n// Method reference\n[StringInList(typeof(MyClass), nameof(MyClass.GetOptions))]\npublic string dynamicOption;\n\n// With int field\n[StringInList(\"Low\", \"Medium\", \"High\")]\npublic int priorityIndex;\nDynamic Options Example:
C#using WallstopStudios.UnityHelpers.Core.Helper;\n\npublic class MySettings\n{\n [StringInList(typeof(Helpers), nameof(Helpers.GetAllSpriteLabelNames))]\n public List<string> selectedLabels;\n}\nFeatures:
SerializableType, so adjusting the page size updates both drawersBest For:
using System.Collections.Generic;\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class StringInListExample : MonoBehaviour\n{\n [StringInList(typeof(StringInListExample), nameof(GetValues))]\n public string value;\n\n private IEnumerable<string> GetValues()\n {\n yield return \"A\";\n yield return \"B\";\n yield return \"C\";\n yield return \"D\";\n }\n}\nVisual Reference
StringInList dropdown showing search filtering and pagination
C#using System.Collections.Generic;\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class StringInListExample : MonoBehaviour\n{\n [StringInList(typeof(StringInListExample), nameof(GetValues))]\n public string value;\n\n private IEnumerable<string> GetValues()\n {\n yield return \"A\";\n yield return \"B\";\n yield return \"C\";\n yield return \"D\";\n }\n}\nVisual Reference
StringInList on a List field with per-element dropdowns and drag reordering
"},{"location":"features/editor-tools/editor-tools-guide/#intdropdown-property-drawer","title":"IntDropdown Property Drawer","text":"Attribute: [IntDropdown]
Purpose: Display int fields as dropdown with specific integer options.
Syntax:
C#[IntDropdown(32, 64, 128, 256, 512, 1024, 2048, 4096, 8192)]\npublic int textureSize;\n\n[IntDropdown(0, 2, 4, 8, 16, 32)]\npublic int padding;\nFeatures:
Best For:
Common Use Cases:
C#using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class IntDropDownExample : MonoBehaviour\n{\n // Texture sizes (power of 2)\n [IntDropDown(32, 64, 128, 256, 512, 1024, 2048, 4096, 8192, 16384)]\n public int maxTextureSize = 2048;\n\n // Padding options\n [IntDropDown(0, 2, 4, 8, 16, 32)]\n public int spritePadding = 4;\n\n // Quality levels\n [IntDropDown(0, 1, 2, 3, 4, 5)]\n public int qualityLevel = 3;\n}\nVisual Reference
IntDropDown for texture sizes showing power-of-two options
"},{"location":"features/editor-tools/editor-tools-guide/#wvaluedropdown-property-drawer","title":"WValueDropDown Property Drawer","text":"Attribute: [WValueDropDown]
Purpose: Generic dropdown for any type with fixed values or provider methods. More flexible than StringInList or IntDropdown \u2014 supports all primitive types, custom classes, and dynamic providers.
Syntax:
C#// Fixed primitive values\n[WValueDropDown(0, 25, 50, 100)]\npublic int staminaThreshold = 50;\n\n[WValueDropDown(0.5f, 1.0f, 1.5f, 2.0f)]\npublic float damageMultiplier = 1.0f;\n\n[WValueDropDown(\"Easy\", \"Normal\", \"Hard\", \"Insane\")]\npublic string difficulty = \"Normal\";\n\n// Static provider method\n[WValueDropDown(typeof(PowerUpLibrary), nameof(PowerUpLibrary.GetAvailablePowerUps))]\npublic PowerUpDefinition selectedPowerUp;\n\n// Instance provider method (context-aware)\n[WValueDropDown(nameof(GetAvailableOptions), typeof(string))]\npublic string selectedOption;\nFeatures:
bool, char, byte, sbyte, short, ushort, int, uint, long, ulong, float, double, stringToString() for labelsBest For:
Custom Types Example:
C#using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\nusing System.Collections.Generic;\n\n[System.Serializable]\npublic class Preset\n{\n public string name;\n public float value;\n\n public override string ToString() => name; // Used for dropdown label\n}\n\npublic class Config : MonoBehaviour\n{\n [WValueDropDown(typeof(Config), nameof(GetPresets))]\n public Preset selectedPreset;\n\n public static IEnumerable<Preset> GetPresets()\n {\n return new[]\n {\n new Preset { name = \"Low\", value = 0.5f },\n new Preset { name = \"Medium\", value = 1.0f },\n new Preset { name = \"High\", value = 2.0f },\n };\n }\n}\nInstance Provider Example:
C#public class DynamicOptions : MonoBehaviour\n{\n public string prefix = \"Option\";\n public int optionCount = 5;\n\n [WValueDropDown(nameof(GetAvailableOptions), typeof(string))]\n public string selectedOption;\n\n private IEnumerable<string> GetAvailableOptions()\n {\n for (int i = 1; i <= optionCount; i++)\n {\n yield return $\"{prefix}_{i}\";\n }\n }\n}\nVisual Reference
WValueDropDown showing predefined integer, float, and string values
For more detailed documentation, including all constructor forms, see Inspector Selection Attributes.
"},{"location":"features/editor-tools/editor-tools-guide/#wreadonly-property-drawer","title":"WReadOnly Property Drawer","text":"Attribute: [WReadOnly]
Purpose: Display fields as read-only in the inspector (grayed out, non-editable).
Syntax:
C#using WallstopStudios.UnityHelpers.Core.Attributes;\n\n[WReadOnly]\npublic int calculatedValue;\n\n[WReadOnly]\npublic string currentState;\nFeatures:
Best For:
Example:
C#using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class WReadOnlyExample : MonoBehaviour\n{\n public int baseHealth = 100;\n public int healthBonus = 0;\n\n [WReadOnly]\n public int totalHealth;\n\n private void OnValidate()\n {\n totalHealth = baseHealth + healthBonus;\n }\n}\nVisual Reference
WReadOnly field showing totalHealth as a non-editable calculated value
For detailed documentation on validation attributes, see Inspector Validation Attributes.
"},{"location":"features/editor-tools/editor-tools-guide/#automation-utilities","title":"Automation & Utilities","text":""},{"location":"features/editor-tools/editor-tools-guide/#scriptableobject-singleton-creator","title":"ScriptableObject Singleton Creator","text":"
[InitializeOnLoad]Purpose: Automatically creates and maintains singleton ScriptableObject assets.
See the base API guide for details on ScriptableObjectSingleton<T> usage, scenarios, and Odin compatibility: Singleton Utilities.
How It Works:
Text Only1. Runs when Unity editor starts\n2. Scans all ScriptableObjectSingleton<T> derived types\n3. Creates missing assets in Assets/Resources/\n4. Moves misplaced singletons to correct locations\n5. Respects [ScriptableSingletonPath] attribute\nUsage Example:
C#using WallstopStudios.UnityHelpers.Utils;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\n// Define singleton:\npublic class GameSettings : ScriptableObjectSingleton<GameSettings>\n{\n public float masterVolume = 1.0f;\n public bool enableVSync = true;\n}\n\n// Optional custom path:\n[ScriptableSingletonPath(\"Settings/Audio\")]\npublic class AudioSettings : ScriptableObjectSingleton<AudioSettings>\n{\n public float musicVolume = 0.8f;\n}\n\n// Assets created automatically:\n// - Assets/Resources/GameSettings.asset\n// - Assets/Resources/Settings/Audio/AudioSettings.asset\n\n// Access at runtime:\nfloat volume = GameSettings.Instance.masterVolume;\nFolder Structure:
Text OnlyAssets/\n Resources/\n GameSettings.asset (no path attribute)\n Settings/\n Audio/ ([ScriptableSingletonPath(\"Settings/Audio\")])\n AudioSettings.asset\nBest For:
Customization:
IncludeTestAssemblies = true to create test singletonsEnsureSingletonAssets() manually to refreshAssetPostprocessorPurpose: Automatically maintains a cache of all sprite labels in the project for fast lookup in editor tools.
How It Works:
What Gets Cached:
Performance Benefits:
Runtime Usage:
C#using WallstopStudios.UnityHelpers.Core.Helper;\n\n// Access cached sprite labels\nstring[] labels = SpriteLabelCache.GetAllLabels();\nTools > Wallstop Studios > Unity Helpers > Request Script CompilationCtrl/Cmd + Alt + R (configurable in Unity's Shortcut Manager)Purpose: Manually trigger Unity script recompilation without needing to modify files or restart the editor.
Visual Reference
Key Features:
When to Use:
Common Workflow:
Text Only1. Run external code generator\n2. Press Ctrl+Alt+R (or use menu item)\n3. Wait for Unity to recompile scripts\n4. Continue working with updated code\nMenu: Edit > Project Settings > Wallstop Studios > Unity Helpers
Purpose: Centralized configuration for Unity Helpers features, including buffer settings, pagination defaults, and inspector behavior.
Visual Reference
Centralized configuration panel in Unity's Project Settings
Key Settings:
"},{"location":"features/editor-tools/editor-tools-guide/#coroutine-wait-buffer-defaults","title":"Coroutine Wait Buffer Defaults","text":"Configure default behavior for WaitForSeconds, WaitForFixedUpdate, and other yield instructions:
// Settings affect runtime buffer pool behavior:\n- Quantization: How yield times are rounded (e.g., 0.1f rounds to nearest 0.1)\n- Entry Caps: Maximum number of cached wait instructions per type\n- LRU Mode: Least-recently-used eviction when caps are exceeded\nImpact:
Generated Asset: Resources/WallstopStudios/UnityHelpers/UnityHelpersBufferSettings.asset
StringInListPageSize: Default page size for StringInList dropdowns (default: 50)WEnumToggleButtonsPageSize: Default page size for enum toggle button grids (default: 20)When to Adjust:
Runtime Usage:
C#using WallstopStudios.UnityHelpers.Core.Helper;\n\n// Get all known sprite labels\nstring[] allLabels = Helpers.GetAllSpriteLabelNames();\n\n// Used internally by StringInList attribute\n[StringInList(typeof(Helpers), nameof(Helpers.GetAllSpriteLabelNames))]\npublic List<string> selectedLabels;\nCache Updates:
Best For:
Technical Notes:
Type: Automatic (runs on editor load and domain reload)
Purpose: Pre-generate attribute system metadata at edit time to eliminate runtime reflection overhead. The cache is automatically regenerated when scripts change. You can manually refresh it via the \"Purge & Refresh Cache\" button in the AttributeMetadataCache asset inspector.
What Gets Cached:
Performance Benefits:
Runtime Usage:
C#// Cache is loaded automatically:\nAttributeMetadataCache cache = AttributeMetadataCache.Instance;\n\n// Get all known attribute names:\nstring[] allAttributes = cache.AllAttributeNames;\n\n// Check type for attribute fields:\nTypeFieldMetadata metadata = cache.GetMetadataForType(typeof(MyAttributesComponent));\nif (metadata != null)\n{\n foreach (string fieldName in metadata.AttributeFieldNames)\n {\n Debug.Log($\"Found attribute field: {fieldName}\");\n }\n}\n\n// Query relational component metadata:\nRelationalTypeMetadata relational = cache.GetRelationalMetadataForType(typeof(MyComponent));\nCache Regenerates:
Best For:
WallstopStudios.UnityHelpers.Editor.UtilsPurpose: Helper methods for Unity Editor operations.
Available Methods:
"},{"location":"features/editor-tools/editor-tools-guide/#getcurrentpathofprojectwindow","title":"GetCurrentPathOfProjectWindow()","text":"Gets the currently selected folder in Unity's Project window.
C#// In an editor window or wizard:\nstring currentFolder = EditorUtilities.GetCurrentPathOfProjectWindow();\nif (!string.IsNullOrEmpty(currentFolder))\n{\n string newAssetPath = $\"{currentFolder}/NewGeneratedAsset.asset\";\n AssetDatabase.CreateAsset(myAsset, newAssetPath);\n}\nelse\n{\n // Fallback to default location\n AssetDatabase.CreateAsset(myAsset, \"Assets/NewGeneratedAsset.asset\");\n}\nReturns: Asset-relative path (e.g., \"Assets/Scripts/Editor\") or empty string.
Use Cases:
Technical Notes:
Best For:
Tools > Wallstop Studios > Unity Helpers > Export Failed Tests / Clear Failed TestsEdit > Project Settings > Wallstop Studios > Unity HelpersPurpose: Hooks into the Unity Test Runner API to automatically capture failed test results and export them to timestamped text files in a configurable directory (defaults to the project root). Disabled by default \u2014 enable in Project Settings.
Key Features:
failed-tests-YYYY-MM-DD-HHmmss.txt in the configured output directory (project root by default)For full setup, usage, and API reference, see Failed Tests Exporter.
"},{"location":"features/editor-tools/editor-tools-guide/#quick-reference","title":"Quick Reference","text":""},{"location":"features/editor-tools/editor-tools-guide/#tools-by-category","title":"Tools by Category","text":"Image Processing:
Animation:
Sprite Atlases:
Quality & Validation:
Custom Editors:
Property Drawers:
Automation:
Utilities:
Tools > Wallstop Studios > Unity Helpers:
Assets > Create > Wallstop Studios > Unity Helpers:
1. Import sprites to Assets/Sprites/\n2. Use Sprite Cropper to remove padding\n3. Use Texture Settings Applier:\n - Filter Mode: Bilinear\n - Wrap Mode: Clamp\n - Compression: CompressedHQ\n4. Use Sprite Settings Applier:\n - Set consistent PPU (e.g., 32 or 64)\n5. Use Sprite Pivot Adjuster for consistent alignment\n1. Prepare sprite frames in folder\n2. Open Sprite Animation Editor\n3. Click \"Browse Clips (Multi)...\" if clips exist, or\n4. Use Animation Creator to generate from sprites\n5. Edit in Sprite Animation Editor:\n - Adjust frame order via drag-drop\n - Set appropriate FPS\n6. Save clips\n7. (Optional) Add animation events:\n a. Open AnimationEvent Editor\n b. Drag Animator to \"Animator Object\" field\n c. Select animation clip\n d. Add events at specific frames\n e. Configure event methods and parameters\n f. Save changes\n1. Create atlas config:\n a. Open Sprite Atlas Generator\n b. Click \"Create New Config in 'Assets/Data'\"\n c. Name your atlas configuration\n2. Configure source folders:\n a. Click \"Add New Source Folder Entry\"\n b. Select folder containing sprites\n c. Add regex patterns (e.g., \"^character_.*\")\n d. Or add labels for filtering\n3. Set packing options:\n - Max texture size (2048 recommended)\n - Padding (4px default)\n - Compression settings\n4. Preview changes:\n a. Click \"Scan Folders\"\n b. Review sprites to add/remove\n5. Generate atlas:\n a. Click \"Add X Sprites\" if satisfied\n b. Click \"Generate/Update .spriteatlas ONLY\"\n c. Click \"Pack All Generated Sprite Atlases\"\n1. Open Prefab Checker\n2. Enable all critical checks:\n - Missing Scripts \u2713\n - Missing Required Components \u2713\n - Null Object References \u2713\n3. Add changed prefab folders\n4. Click \"Run Checks\"\n5. Fix all reported issues\n6. Re-run to verify\n7. Commit changes\n1. Use Sprite Cropper on all sprites (reduces memory)\n2. Use Texture Settings Applier with:\n - Appropriate compression for platform\n - Crunch compression enabled\n - Proper max texture sizes\n3. Review build report for texture memory usage\n4. Iterate on settings as needed\nSprite Animation Editor:
Enter in frame order field: Apply frame reorderingPrefab Checker:
General:
Sprite Cropper:
Texture Settings Applier:
Prefab Checker:
Attribute Metadata Cache:
Tool window won't open:
Settings not applying:
Cache not regenerating:
Prefab Checker missing issues:
Organization:
Performance:
Quality:
Workflow:
Compilation helpers:
Tools > Wallstop Studios > Unity Helpers > Request Script CompilationCtrl/Cmd + Alt + R (configurable via Unity\u2019s Shortcut Manager under Wallstop / Request Script Compilation)AssetDatabase.Refresh (synchronous import) before calling CompilationPipeline.RequestScriptCompilation() and logs whenever Unity is already compiling so scripts created outside the editor are imported immediately.Attributes System:
[ValidateAssignment] for prefab validation[ScriptableSingletonPath] for custom singleton paths[ParentComponent], [ChildComponent], [SiblingComponent] for relational queriesRelated Components:
ScriptableObjectSingleton<T> - Base class for settingsAttributesComponent - Base class for the attribute systemLayeredImage - UI Toolkit multi-layer sprite renderingDocument Version: 2.0 Package: com.wallstop-studios.unity-helpers Last Updated: 2025-10-08
What's New in v2.0:
This package provides 20+ editor tools across multiple categories:
14 Editor Windows/Wizards:
3 Custom Component Editors:
4 Property Drawers:
3 Automated Systems:
1 Utility Library:
All tools are designed to work together seamlessly and follow consistent design patterns for ease of use.
For questions, issues, or feature requests, please contact the Wallstop Studios team.
AttributeModification.attribute field. See Effects System for how attributes, effects, and tags fit together.MultiFileSelectorElement is primarily intended for Editor tooling. It can also be used in player builds, where it enumerates files under the application\u2019s data root. In the Editor it integrates with EditorPrefs and Reveal-in-Finder; at runtime it falls back to PlayerPrefs and omits Editor-only affordances.The Failed Tests Exporter is an editor utility that hooks into the Unity Test Runner API to automatically capture failed test results. When a test run completes, it records each failure's name, message, and stack trace, and can export them to a timestamped text file in a configurable directory (defaults to the project root).
This is especially useful for CI/CD pipelines where you need a machine-readable artifact of test failures, or for tracking intermittent test failures across multiple runs.
"},{"location":"features/editor-tools/failed-tests-exporter/#setup","title":"Setup","text":"The Failed Tests Exporter is disabled by default. To enable it:
Edit > Project Settings)The exporter activates immediately when the setting is toggled. No domain reload is required.
"},{"location":"features/editor-tools/failed-tests-exporter/#output-directory","title":"Output Directory","text":"By default, failed test result files are written to the project root. You can configure a different output directory:
The output directory field is read-only to prevent typos \u2014 use the Browse\u2026 button to select a folder visually.
Path Validation
The output directory is validated on every use:
.., and paths outside the project root are rejectedWhen enabled, the exporter automatically:
The output file is written to the configured output directory (or the project root if none is set) with the format failed-tests-YYYY-MM-DD-HHmmss.txt.
You can manually export or clear captured failures using the menu items:
Both menu items are only enabled when there are captured failures.
"},{"location":"features/editor-tools/failed-tests-exporter/#output-format","title":"Output Format","text":"Each failure in the exported file includes:
Text OnlyTEST_FAILURE_1\nName: MyNamespace.MyTestClass.MyTestMethod\nMessage: Expected 42 but was 0\nStack Trace:\nat MyNamespace.MyTestClass.MyTestMethod() in /path/to/file.cs:line 25\n\n---\n\nTEST_FAILURE_2\nName: MyNamespace.MyOtherClass.AnotherTest\nMessage: Object reference not set\nStack Trace:\n(no stack trace)\nNote: The FailedTestsExporter class and its nested FailedTestInfo struct are internal and primarily intended for use within the Unity Helpers assembly. External consumers interact with this feature through the menu items and the settings UI described above.
Instance FailedTestsExporter Static reference to the active exporter instance (null when disabled) Failures IReadOnlyList<FailedTestInfo> Read-only list of captured test failures IsEnabled() bool Whether the exporter is enabled in Unity Helpers settings"},{"location":"features/editor-tools/failed-tests-exporter/#failedtestinfo","title":"FailedTestInfo","text":"Field Type Description name string Fully qualified test name message string Failure message (or empty string) stackTrace string Stack trace (or empty string)"},{"location":"features/editor-tools/failed-tests-exporter/#see-also","title":"See Also","text":"Detect C# inheritance issues and Unity lifecycle errors across your entire codebase.
The Unity Method Analyzer scans your project's C# files and identifies common mistakes in method overrides, Unity lifecycle methods, and inheritance patterns\u2014before they cause runtime bugs. Use it during development to catch silent failures, missing base calls, and signature mismatches.
"},{"location":"features/editor-tools/unity-method-analyzer/#table-of-contents","title":"Table of Contents","text":"The Unity Method Analyzer provides:
Common issues detected:
Issue Type Example Missingoverride keyword Hiding base method instead of overriding Wrong method signature OnCollisionEnter(Collider c) instead of OnCollisionEnter(Collision c) Shadowed lifecycle methods Both base and derived class have private void Start() Return type mismatches void Start() vs IEnumerator Start() in inheritance chain Static lifecycle methods static void Awake() won't be called by Unity"},{"location":"features/editor-tools/unity-method-analyzer/#getting-started","title":"Getting Started","text":""},{"location":"features/editor-tools/unity-method-analyzer/#opening-the-analyzer","title":"Opening the Analyzer","text":"Menu: Tools > Wallstop Studios > Unity Helpers > Unity Method Analyzer
The analyzer groups issues into three categories:
"},{"location":"features/editor-tools/unity-method-analyzer/#unity-lifecycle-issues","title":"Unity Lifecycle Issues","text":"Problems with Unity's magic methods (Start, Update, OnCollisionEnter, etc.):
// \u274c WRONG: Unexpected parameters - Unity won't call this\nvoid Update(float deltaTime) // Update takes no parameters\n{\n Move(deltaTime);\n}\n\n// \u2705 CORRECT: Proper signature\nvoid Update()\n{\n Move(Time.deltaTime);\n}\n// \u274c WRONG: Static lifecycle method - Unity won't call it\nstatic void Awake()\n{\n Initialize();\n}\n\n// \u2705 CORRECT: Instance method\nvoid Awake()\n{\n Initialize();\n}\n// \u26a0\ufe0f SHADOWING: Both base and derived have private Start()\npublic class BaseEnemy : MonoBehaviour\n{\n private void Start() { BaseInit(); } // Called for BaseEnemy instances\n}\n\npublic class Boss : BaseEnemy\n{\n private void Start() { BossInit(); } // Only this is called for Boss instances\n}\n\n// \u2705 BETTER: Use virtual/override pattern\npublic class BaseEnemy : MonoBehaviour\n{\n protected virtual void Start() { BaseInit(); }\n}\n\npublic class Boss : BaseEnemy\n{\n protected override void Start()\n {\n base.Start(); // Calls BaseInit()\n BossInit();\n }\n}\nProblems when extending Unity base classes:
C#public class GameManager : MonoBehaviour\n{\n // \u274c WRONG: Using 'new' hides the base method\n public new void Awake()\n {\n Initialize();\n }\n\n // \u2705 CORRECT: Use virtual/override pattern if base is virtual\n // Or just declare normally for MonoBehaviour lifecycle\n private void Awake()\n {\n Initialize();\n }\n}\nProblems in your own class hierarchies:
C#public class BaseEnemy : MonoBehaviour\n{\n public virtual void TakeDamage(int amount) { }\n}\n\npublic class Boss : BaseEnemy\n{\n // \u274c WRONG: Missing 'override' keyword - hides base method\n public void TakeDamage(int amount)\n {\n // This won't be called polymorphically!\n }\n\n // \u2705 CORRECT: Properly override\n public override void TakeDamage(int amount)\n {\n base.TakeDamage(amount);\n // Boss-specific logic\n }\n}\nConfigure which directories to scan:
Tip: Add only relevant directories (e.g., Assets/Scripts) to speed up analysis.
The results are displayed in a hierarchical tree view:
When you select an issue, the detail panel shows:
Organize results by:
Focus on specific severity levels:
"},{"location":"features/editor-tools/unity-method-analyzer/#category-filter","title":"Category Filter","text":"Focus on specific issue categories:
Free-text search across all issue fields:
Search matches against:
Click \"Export \u25be\" to access export options:
"},{"location":"features/editor-tools/unity-method-analyzer/#copy-options","title":"Copy Options","text":"{\n \"analysisDate\": \"2024-01-15T10:30:00Z\",\n \"totalIssues\": 12,\n \"issues\": [\n {\n \"filePath\": \"Assets/Scripts/Player/PlayerController.cs\",\n \"className\": \"PlayerController\",\n \"methodName\": \"OnCollisionEnter\",\n \"issueType\": \"Unity Lifecycle Signature Mismatch\",\n \"description\": \"Method 'OnCollisionEnter' has wrong parameter type\",\n \"severity\": \"High\",\n \"recommendedFix\": \"Change parameter from 'Collider' to 'Collision'\",\n \"lineNumber\": 42,\n \"category\": \"UnityLifecycle\"\n }\n ]\n}\n# Unity Method Analyzer Report\n\nGenerated: 2024-01-15 10:30:00\nTotal Issues: 12\n\n## Critical (2)\n\n### PlayerController.cs:42\n\n**Class:** PlayerController \n**Method:** OnCollisionEnter \n**Issue:** Unity Lifecycle Signature Mismatch \n**Fix:** Change parameter from 'Collider' to 'Collision'\nFor test code or intentional patterns, use [SuppressAnalyzer]:
using WallstopStudios.UnityHelpers.Tests.Core;\n\n// Suppress entire class\n[SuppressAnalyzer(\"Test fixture for analyzer validation\")]\npublic class TestClassWithIntentionalIssues : BaseClass\n{\n public void HiddenMethod() { } // Won't trigger warning\n}\n\n// Or suppress specific methods\npublic class TestClass : BaseClass\n{\n [SuppressAnalyzer(\"Testing method hiding detection\")]\n public new void VirtualMethod() { } // Won't trigger warning\n}\nNote: [SuppressAnalyzer] is only available in test assemblies. Production code should fix issues rather than suppress them.
Assets/Scripts folderExport JSON reports and parse them in your build pipeline:
Bash# Example: Fail build if critical issues exist\nunity -batchmode -projectPath . -executeMethod AnalyzerRunner.RunAndExport\ncat analyzer-report.json | jq '.issues | map(select(.severity == \"Critical\")) | length'\nTools > Wallstop Studios > Unity Helpers > Unity Method Analyzer Issue Categories Unity Lifecycle, Unity Inheritance, General Inheritance Severity Levels Critical, High, Medium, Low, Info Export Formats JSON, Markdown Suppression [SuppressAnalyzer] attribute (test assemblies only)"},{"location":"features/effects/effects-system-tutorial/","title":"Effects System Tutorial - Build Your First Buff in 5 Minutes","text":""},{"location":"features/effects/effects-system-tutorial/#what-youll-build","title":"What You'll Build","text":"By the end of this tutorial, you'll have a complete working buff system with:
Time required: 5-10 minutes
"},{"location":"features/effects/effects-system-tutorial/#why-use-the-effects-system","title":"Why Use the Effects System?","text":"The Old Way:
C#// 50-100 lines per effect type\npublic class HasteEffect : MonoBehaviour {\n float duration;\n float speedMultiplier;\n GameObject particles;\n\n void Update() {\n duration -= Time.deltaTime;\n if (duration <= 0) RemoveSelf();\n }\n\n void RemoveSelf() {\n // Remove speed modifier...\n // Destroy particles...\n // Handle stacking...\n // 40 more lines...\n }\n}\nThe New Way:
C#// Zero lines - everything configured in editor\nplayer.ApplyEffect(hasteEffect); // Done!\nResult: Designers create hundreds of effects without programmer involvement.
"},{"location":"features/effects/effects-system-tutorial/#step-1-create-your-first-attributescomponent-2-minutes","title":"Step 1: Create Your First AttributesComponent (2 minutes)","text":"This component will hold the stats that effects can modify.
C#using UnityEngine;\nusing WallstopStudios.UnityHelpers.Tags;\n\npublic class PlayerStats : AttributesComponent\n{\n // Define attributes that effects can modify\n public Attribute Speed = 5f;\n public Attribute MaxHealth = 100f;\n public Attribute AttackDamage = 10f;\n public Attribute Defense = 5f;\n\n protected override void Awake()\n {\n base.Awake();\n // Optional: Log when attributes change\n OnAttributeModified += (attributeName, oldVal, newVal) =>\n Debug.Log($\"{attributeName} changed: {oldVal} \u2192 {newVal}\");\n }\n}\nWhat's an Attribute?
\u26a0\ufe0f Important: Use Attributes for \"max\" or \"rate\" values, NOT \"current\" depleting values!
If a value is frequently modified by systems outside the effects system (like health being reduced by damage), use a regular field instead. See the main documentation for details.
"},{"location":"features/effects/effects-system-tutorial/#step-2-add-stats-to-your-player-30-seconds","title":"Step 2: Add Stats to Your Player (30 seconds)","text":"PlayerStats5100105That's it! Your player now has modifiable attributes.
"},{"location":"features/effects/effects-system-tutorial/#step-3-create-a-haste-effect-2-minutes","title":"Step 3: Create a Haste Effect (2 minutes)","text":""},{"location":"features/effects/effects-system-tutorial/#31-create-the-scriptableobject","title":"3.1 Create the ScriptableObject","text":"Right-click \u2192 Create \u2192 Wallstop Studios \u2192 Unity Helpers \u2192 Attribute EffectHasteEffectSelect HasteEffect and set these values in Inspector:
Modifications:
Speed (must match field name exactly)Multiplication1.5 (150% of base speed)Duration:
Duration5 (seconds)Tags:
\"Haste\" (used for both gameplay queries via HasTag() and effect organization)Cosmetic Effects:
1Add this code to test your effect:
C#using UnityEngine;\nusing WallstopStudios.UnityHelpers.Tags;\n\npublic class PlayerController : MonoBehaviour\n{\n [SerializeField] private AttributeEffect hasteEffect;\n private PlayerStats stats;\n\n void Start()\n {\n stats = GetComponent<PlayerStats>();\n }\n\n void Update()\n {\n // Apply haste when pressing H\n if (Input.GetKeyDown(KeyCode.H))\n {\n this.ApplyEffect(hasteEffect);\n Debug.Log($\"Speed is now: {stats.Speed.CurrentValue}\");\n }\n\n // Move with current speed\n float h = Input.GetAxis(\"Horizontal\");\n transform.position += Vector3.right * h * stats.Speed * Time.deltaTime;\n }\n}\nTest it:
HasteEffect to the Inspector fieldH to apply hasteLet's make a more complex effect that prevents movement.
"},{"location":"features/effects/effects-system-tutorial/#51-create-the-effect","title":"5.1 Create the Effect","text":"Right-click \u2192 Create \u2192 Wallstop Studios \u2192 Unity Helpers \u2192 Attribute EffectStunEffectModifications:
SpeedOverride0 (completely override speed to 0)Duration:
Duration3Tags:
\"Stunned\", \"Stun\", \"Debuff\", \"CC\" (for gameplay queries and organization)public class PlayerController : MonoBehaviour\n{\n [SerializeField] private AttributeEffect hasteEffect;\n [SerializeField] private AttributeEffect stunEffect;\n private PlayerStats stats;\n\n void Update()\n {\n // Apply effects\n if (Input.GetKeyDown(KeyCode.H)) this.ApplyEffect(hasteEffect);\n if (Input.GetKeyDown(KeyCode.S)) this.ApplyEffect(stunEffect);\n\n // Check if player is stunned before allowing movement\n if (this.HasTag(\"Stunned\"))\n {\n Debug.Log(\"Player is stunned! Cannot move.\");\n return;\n }\n\n // Normal movement\n float h = Input.GetAxis(\"Horizontal\");\n transform.position += Vector3.right * h * stats.Speed * Time.deltaTime;\n }\n}\nTest it:
S to stun yourselfEffects stack independently by default:
C#// Apply haste 3 times\nthis.ApplyEffect(hasteEffect); // Speed = 7.5\nthis.ApplyEffect(hasteEffect); // Speed = 11.25 (1.5 \u00d7 1.5 \u00d7 5)\nthis.ApplyEffect(hasteEffect); // Speed = 16.875 (1.5 \u00d7 1.5 \u00d7 1.5 \u00d7 5)\n\n// Each stack has its own duration and can be removed independently\n// Apply and save handle\nEffectHandle? handle = this.ApplyEffect(hasteEffect);\n\n// Remove specific stack early\nif (handle.HasValue)\n{\n this.RemoveEffect(handle.Value);\n}\n\n// Remove all haste effects\nthis.RemoveEffects(this.GetHandlesWithTag(\"Haste\"));\nOne effect can modify multiple attributes:
Create \"Berserker Rage\" effect:
\"Berserker\", \"Buff\"For permanent buffs (e.g., equipment):
C#// In Inspector:\n// - Modifier Duration Type: Infinite\n// - (Duration field is ignored)\n\n// Apply permanent buff\nEffectHandle? handle = this.ApplyEffect(permanentStrengthBonus);\n\n// Later, remove when equipment is unequipped\nif (handle.HasValue)\n this.RemoveEffect(handle.Value);\n// Create \"Poison\" effect:\n// - periodicEffects: interval = 1s, maxTicks = 10, modifications = []\n// - behaviors: PoisonDamageBehavior (below)\n// - Duration: 10 seconds\n// - Tags: \"Poisoned\", \"DoT\", \"Debuff\"\n\nvoid ApplyPoison(GameObject target)\n{\n target.ApplyEffect(poisonEffect);\n}\n\n[CreateAssetMenu(menuName = \"Combat/Effects/Poison Damage\")]\npublic sealed class PoisonDamageBehavior : EffectBehavior\n{\n [SerializeField]\n private float damagePerTick = 2f;\n\n public override void OnPeriodicTick(\n EffectBehaviorContext context,\n PeriodicEffectTickContext tickContext\n )\n {\n if (!context.Target.TryGetComponent(out PlayerHealth health))\n {\n return;\n }\n\n health.ApplyDamage(damagePerTick);\n }\n}\n\npublic sealed class PlayerHealth : MonoBehaviour\n{\n [SerializeField]\n private float currentHealth = 100f;\n\n public float CurrentHealth => currentHealth;\n\n public void ApplyDamage(float amount)\n {\n currentHealth -= amount;\n\n if (currentHealth <= 0f)\n {\n currentHealth = 0f;\n Die();\n }\n }\n\n private void Die()\n {\n // Handle player death\n }\n}\nThis keeps CurrentHealth as a regular gameplay field while the effect system triggers damage through behaviours.
// Create \"Haste\" effect (for abilities):\n// - Modification: CooldownRate \u00d7 1.5 (50% faster cooldowns)\n\npublic class AbilitySystem : AttributesComponent\n{\n public Attribute CooldownRate = 1f;\n private float cooldown;\n\n public void UseAbility()\n {\n // Cooldown respects rate\n cooldown = baseCooldown / CooldownRate.Value;\n }\n}\n// Only apply effect if conditions met\nvoid TryApplyBuff(AttributeEffect effect)\n{\n // Check if player already has max buffs\n if (this.TryGetTagCount(\"Buff\", out int buffCount) && buffCount >= 5)\n {\n Debug.Log(\"Too many buffs active!\");\n return;\n }\n\n // Check if effect is already active\n if (this.HasTag(\"Haste\") && effect == hasteEffect)\n {\n Debug.Log(\"Haste already active!\");\n return;\n }\n\n this.ApplyEffect(effect);\n}\nMaxHealth as an Attribute (modified by buffs), but keep CurrentHealth as a regular field (modified by damage/healing)Speed not speedAttributesComponent?EffectHandler component added? (Usually added automatically)CosmeticEffectData componentattribute.Value before and after applying effectYou now have a complete buff/debuff system! Here are some ideas to expand:
"},{"location":"features/effects/effects-system-tutorial/#create-more-effects","title":"Create More Effects","text":"// AI ignores invisible players\nif (!target.HasTag(\"Invisible\"))\n{\n ChasePlayer(target);\n}\n\n// UI shows status icons\nif (player.HasTag(\"Poisoned\"))\n ShowPoisonIcon();\n\n// Abilities check prerequisites\nif (player.HasTag(\"Stunned\") || player.HasTag(\"Silenced\"))\n return; // Can't cast\n\n// Interactions respect state\nif (player.HasTag(\"Invulnerable\"))\n damage = 0;\nCore Guides:
Related Features:
Need help? Open an issue
"},{"location":"features/effects/effects-system-tutorial/#made-with-by-wallstop-studios","title":"Made with \u2764\ufe0f by Wallstop Studios","text":"Effects System tutorial complete! Your designers can now create gameplay effects without code.
"},{"location":"features/effects/effects-system/","title":"Effects, Attributes, and Tags \u2014 Deep Dive","text":""},{"location":"features/effects/effects-system/#tldr-what-problem-this-solves","title":"TL;DR \u2014 What Problem This Solves","text":"The Problem - Hardcoded Effects:
C#// Every buff needs its own custom MonoBehaviour:\n\npublic class HasteEffect : MonoBehaviour\n{\n private float duration = 5f;\n private float originalSpeed;\n private PlayerStats player;\n\n void Start()\n {\n player = GetComponent<PlayerStats>();\n originalSpeed = player.speed;\n player.speed *= 1.5f; // Apply speed boost\n }\n\n void Update()\n {\n duration -= Time.deltaTime;\n if (duration <= 0)\n {\n player.speed = originalSpeed; // Restore\n Destroy(this);\n }\n }\n}\n\n// 20 effects \u00d7 50 lines each = 1000 lines of repetitive code\n// Designers can't create effects without programmer\nThe Solution - Data-Driven:
C#// Programmers build system once (Unity Helpers provides this):\n// - AttributesComponent base class\n// - EffectHandler manages application/removal\n// - ScriptableObject authoring\n\n// Designers create effects in Editor (NO CODE):\n// 1. Right-click \u2192 Create \u2192 Attribute Effect\n// 2. Name: \"Haste\"\n// 3. Add modification: Speed \u00d7 1.5\n// 4. Duration: 5 seconds\n// 5. Done!\n\n// Apply at runtime (one line):\ntarget.ApplyEffect(hasteEffect);\nDesigner Workflow:
Impact:
Data\u2011driven gameplay effects that modify stats, apply tags, and drive cosmetic presentation.
This guide explains the concepts, how they work together, authoring patterns, recipes, best practices, and FAQs.
"},{"location":"features/effects/effects-system/#visual-reference","title":"Visual Reference","text":""},{"location":"features/effects/effects-system/#concepts","title":"Concepts","text":"Attribute \u2014 A dynamic numeric value with a base and a calculated current value. Current value applies all active modifications.AttributeModification \u2014 Declarative change to an Attribute. Actions: Addition, Multiplication, Override. Applied in that order.AttributeEffect \u2014 ScriptableObject asset bundling modifications, tags, cosmetic data, duration policy, periodic tick schedules, and optional runtime behaviours.EffectHandle \u2014 Opaque identifier for a specific application instance (for Duration/Infinite effects). Used to remove one stack.AttributesComponent \u2014 Base MonoBehaviour exposing modifiable Attribute fields (e.g., Health, Speed) on your character.EffectHandler \u2014 Component that applies/removes effects, tracks durations, forwards modifications to AttributesComponent, applies tags and cosmetics.TagHandler \u2014 Counts and queries string tags for gating gameplay (e.g., \"Stunned\"). Removes tags only when all sources are gone.CosmeticEffectData \u2014 Prefab\u2011like container with CosmeticEffectComponent behaviours; reused or instanced per effect application.AttributeEffect with modifications, tags, cosmetics, and duration.EffectHandle? handle = target.ApplyEffect(effect);EffectHandler will:EffectHandle (for Duration/Infinite) and track expirationTagHandler (counted; multiple sources safe)CosmeticEffectData)AttributeModifications to all AttributesComponents on the GameObjectInstant effects modify base values permanently and return null instead of a handle.
public class CharacterStats : AttributesComponent\n{\n public Attribute MaxHealth = 100f;\n public Attribute Speed = 5f;\n public Attribute AttackDamage = 10f;\n public Attribute Defense = 10f;\n}\nAttributeEffect asset (Project view \u2192 Create \u2192 Wallstop Studios \u2192 Unity Helpers \u2192 Attribute Effect):{ attribute: \"Speed\", action: Multiplication, value: 1.5f }Duration with duration = 5[ \"Haste\" ]cosmeticEffects: prefab with CosmeticEffectData + CosmeticEffectComponent scripts
Apply/remove at runtime:
GameObject player = ...;\nAttributeEffect haste = ...; // ScriptableObject reference\nEffectHandle? handle = player.ApplyEffect(haste);\n// ... later ...\nif (handle.HasValue)\n{\n player.RemoveEffect(handle.Value);\n}\nif (player.HasTag(\"Stunned\"))\n{\n // Disable input, play animation, etc.\n}\nImportant: Attributes are NOT required! The Effects System works well when used solely for tag-based state management and cosmetic effects.
"},{"location":"features/effects/effects-system/#what-makes-a-good-attribute","title":"What Makes a Good Attribute?","text":"Attributes work best for values that are:
\u274c DON'T use Attributes for \"current\" values like CurrentHealth, CurrentMana, or CurrentAmmo!
Why? These values are frequently modified by multiple systems:
The Problem:
C#// \u274c BAD: CurrentHealth as an Attribute\npublic class PlayerStats : AttributesComponent\n{\n public Attribute CurrentHealth = 100f; // DON'T DO THIS!\n public Attribute MaxHealth = 100f; // This is fine\n}\n\n// Multiple systems modify CurrentHealth:\nvoid TakeDamage(float damage)\n{\n // Direct mutation bypasses the effects system\n playerStats.CurrentHealth.BaseValue -= damage;\n\n // Problem 1: If an effect was modifying CurrentHealth,\n // it still applies! Now calculations are wrong.\n // Problem 2: If you remove an effect, it may restore\n // the ORIGINAL base value, undoing damage taken.\n // Problem 3: Save/load becomes complicated - do you save\n // base or current? What about active modifiers?\n}\nThe Solution - Separate Current and Max:
C#// \u2705 GOOD: CurrentHealth is a regular field, MaxHealth is an Attribute\npublic class PlayerStats : AttributesComponent\n{\n // Regular field - modified by combat/healing systems directly\n private float currentHealth = 100f;\n\n // Attribute - modified by buffs/effects\n public Attribute MaxHealth = 100f;\n\n public float CurrentHealth\n {\n get => currentHealth;\n set => currentHealth = Mathf.Clamp(value, 0, MaxHealth.Value);\n }\n\n protected override void Awake()\n {\n base.Awake();\n // Initialize current health to max\n currentHealth = MaxHealth.Value;\n\n // When max health changes, clamp current health\n OnAttributeModified += (attributeName, oldVal, newVal) =>\n {\n if (attributeName == nameof(MaxHealth))\n {\n // If max decreased, ensure current doesn't exceed new max\n if (currentHealth > newVal)\n {\n currentHealth = newVal;\n }\n }\n };\n }\n}\n\n// Combat system can now safely modify current health\nvoid TakeDamage(float damage)\n{\n playerStats.CurrentHealth -= damage; // Simple and correct\n}\n\n// Effects system modifies max health\nvoid ApplyHealthBuff()\n{\n // MaxHealth \u00d7 1.5 (buffs max, current stays same)\n player.ApplyEffect(healthBuffEffect);\n}\n\u2705 DO use Attributes for:
\u274c DON'T use Attributes for:
When you use Attributes for frequently mutated \"current\" values:
The Golden Rule: If a value is modified by systems outside the effects system regularly (combat, regeneration, consumption), it should NOT be an Attribute. Use a regular field instead and let Attributes handle the maximums/limits.
"},{"location":"features/effects/effects-system/#using-tags-without-attributes","title":"Using Tags WITHOUT Attributes","text":"Even without any Attributes, the Effects System is useful for tag-based state management and cosmetic effects.
"},{"location":"features/effects/effects-system/#when-to-use-tags-without-attributes","title":"When to Use Tags Without Attributes","text":"You should consider tag-only effects when:
// No AttributesComponent needed!\npublic class StealthCharacter : MonoBehaviour\n{\n [SerializeField] private AttributeEffect invisibilityEffect;\n [SerializeField] private AttributeEffect stunnedEffect;\n\n void Start()\n {\n // Apply invisibility for 5 seconds\n // InvisibilityEffect.asset:\n // - durationType: Duration (5 seconds)\n // - effectTags: [\"Invisible\", \"Stealthy\"]\n // - modifications: (EMPTY - no attributes needed!)\n // - cosmeticEffects: shimmer particles\n this.ApplyEffect(invisibilityEffect);\n }\n\n void Update()\n {\n // Check tags to gate behavior\n if (this.HasTag(\"Stunned\"))\n {\n // Prevent all actions\n return;\n }\n\n // AI can't detect invisible characters\n if (!this.HasTag(\"Invisible\"))\n {\n BroadcastPosition();\n }\n }\n}\nTags with durations provide automatic cleanup for visual effects:
C#// Create a \"ShowDamageIndicator\" effect:\n// DamageIndicator.asset:\n// - durationType: Duration (1.5 seconds)\n// - effectTags: [\"DamageIndicator\"]\n// - modifications: (EMPTY)\n// - cosmeticEffects: DamageNumbersPrefab\n\npublic class CombatFeedback : MonoBehaviour\n{\n [SerializeField] private AttributeEffect damageIndicator;\n\n public void ShowDamage(float amount)\n {\n // Apply effect - cosmetic spawns automatically\n this.ApplyEffect(damageIndicator);\n\n // After 1.5 seconds, cosmetic is automatically cleaned up\n // No manual cleanup code needed!\n }\n}\n1. Temporary Permissions:
C#// PowerUpEffect.asset:\n// - durationType: Duration (10 seconds)\n// - effectTags: [\"CanDash\", \"CanDoubleJump\", \"PoweredUp\"]\n// - modifications: (EMPTY)\n\npublic void GrantPowerUp()\n{\n player.ApplyEffect(powerUpEffect);\n // Player now has special abilities for 10 seconds\n}\n2. State Management:
C#// DialogueStateEffect.asset:\n// - durationType: Infinite\n// - effectTags: [\"InDialogue\", \"InputDisabled\"]\n\nEffectHandle? dialogueHandle = player.ApplyEffect(dialogueState);\n// ... dialogue system runs ...\nplayer.RemoveEffect(dialogueHandle.Value);\n3. Visual-Only Effects:
C#// LevelUpEffect.asset:\n// - durationType: Duration (2 seconds)\n// - effectTags: [\"LevelingUp\"]\n// - cosmeticEffects: GlowParticles, LevelUpSound\n\nplayer.ApplyEffect(levelUpEffect);\n// Particles and sound play, then clean up automatically\nCosmetic effects handle the visual and audio presentation of effects. They provide a clean separation between gameplay logic (tags, attributes) and presentation (particles, sounds, UI).
"},{"location":"features/effects/effects-system/#architecture-overview","title":"Architecture Overview","text":"Component Hierarchy:
Text OnlyCosmeticEffectData (Container GameObject/Prefab)\n \u2514\u2500 CosmeticEffectComponent (Base class - abstract)\n \u2514\u2500 Your custom implementations:\n - ParticleCosmeticEffect\n - AudioCosmeticEffect\n - UICosmeticEffect\n - AnimationCosmeticEffect\nCosmeticEffectDataAttributeEffect.cosmeticEffects listusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Tags;\n\npublic class ParticleCosmeticEffect : CosmeticEffectComponent\n{\n [SerializeField] private ParticleSystem particles;\n\n // RequiresInstance = true creates a new instance per application\n // RequiresInstance = false shares one instance across all applications\n public override bool RequiresInstance => true;\n\n // CleansUpSelf = true means you handle destruction yourself\n // CleansUpSelf = false means EffectHandler destroys the GameObject\n public override bool CleansUpSelf => false;\n\n public override void OnApplyEffect(GameObject target)\n {\n base.OnApplyEffect(target);\n\n // Attach cosmetic to target\n transform.SetParent(target.transform);\n transform.localPosition = Vector3.zero;\n\n // Start visual effect\n particles.Play();\n }\n\n public override void OnRemoveEffect(GameObject target)\n {\n base.OnRemoveEffect(target);\n\n // Stop particles\n particles.Stop();\n\n // If CleansUpSelf = false, GameObject is destroyed automatically\n // If CleansUpSelf = true, you must handle destruction\n }\n}\nRequiresInstance = false (Shared):
public class StatusIconCosmetic : CosmeticEffectComponent\n{\n public override bool RequiresInstance => false; // SHARED\n\n [SerializeField] private Image iconImage;\n private int activeCount = 0;\n\n public override void OnApplyEffect(GameObject target)\n {\n base.OnApplyEffect(target);\n activeCount++;\n\n // Show icon if this is first application\n if (activeCount == 1)\n {\n iconImage.enabled = true;\n }\n }\n\n public override void OnRemoveEffect(GameObject target)\n {\n base.OnRemoveEffect(target);\n activeCount--;\n\n // Hide icon when no more applications\n if (activeCount == 0)\n {\n iconImage.enabled = false;\n }\n }\n}\nRequiresInstance = true (Instanced):
public class FireParticleCosmetic : CosmeticEffectComponent\n{\n public override bool RequiresInstance => true; // INSTANCED\n\n [SerializeField] private ParticleSystem fireParticles;\n\n public override void OnApplyEffect(GameObject target)\n {\n base.OnApplyEffect(target);\n\n // Each instance is independent\n transform.SetParent(target.transform);\n transform.localPosition = Vector3.zero;\n fireParticles.Play();\n }\n}\nCleansUpSelf = false (Automatic - Default):
public class SimpleParticleEffect : CosmeticEffectComponent\n{\n public override bool CleansUpSelf => false; // AUTOMATIC\n\n public override void OnRemoveEffect(GameObject target)\n {\n base.OnRemoveEffect(target);\n // GameObject destroyed automatically by EffectHandler\n }\n}\nCleansUpSelf = true (Manual Cleanup):
public class FadeOutEffect : CosmeticEffectComponent\n{\n public override bool CleansUpSelf => true; // MANUAL\n\n [SerializeField] private float fadeOutDuration = 1f;\n private bool isRemoving = false;\n\n public override void OnRemoveEffect(GameObject target)\n {\n base.OnRemoveEffect(target);\n\n if (!isRemoving)\n {\n isRemoving = true;\n StartCoroutine(FadeOutAndDestroy());\n }\n }\n\n private IEnumerator FadeOutAndDestroy()\n {\n // Fade out over time\n float elapsed = 0f;\n SpriteRenderer sprite = GetComponent<SpriteRenderer>();\n Color originalColor = sprite.color;\n\n while (elapsed < fadeOutDuration)\n {\n elapsed += Time.deltaTime;\n float alpha = 1f - (elapsed / fadeOutDuration);\n sprite.color = new Color(originalColor.r, originalColor.g, originalColor.b, alpha);\n yield return null;\n }\n\n // Now safe to destroy\n Destroy(gameObject);\n }\n}\npublic class BuffCosmetic : CosmeticEffectComponent\n{\n [SerializeField] private ParticleSystem buffParticles;\n [SerializeField] private AudioSource audioSource;\n [SerializeField] private AudioClip applySound;\n [SerializeField] private AudioClip removeSound;\n\n public override bool RequiresInstance => true;\n public override bool CleansUpSelf => false;\n\n public override void OnApplyEffect(GameObject target)\n {\n base.OnApplyEffect(target);\n\n // Position cosmetic on target\n transform.SetParent(target.transform);\n transform.localPosition = Vector3.zero;\n\n // Play effects\n buffParticles.Play();\n audioSource.PlayOneShot(applySound);\n }\n\n public override void OnRemoveEffect(GameObject target)\n {\n base.OnRemoveEffect(target);\n\n audioSource.PlayOneShot(removeSound);\n buffParticles.Stop();\n // Automatic cleanup after this\n }\n}\npublic class StatusOverlayCosmetic : CosmeticEffectComponent\n{\n [SerializeField] private SpriteRenderer overlaySprite;\n [SerializeField] private Color overlayColor = Color.red;\n\n public override bool RequiresInstance => false; // SHARED\n public override bool CleansUpSelf => false;\n\n private SpriteRenderer targetSprite;\n\n public override void OnApplyEffect(GameObject target)\n {\n base.OnApplyEffect(target);\n\n targetSprite = target.GetComponent<SpriteRenderer>();\n if (targetSprite != null)\n {\n // Tint the sprite\n targetSprite.color = overlayColor;\n }\n }\n\n public override void OnRemoveEffect(GameObject target)\n {\n base.OnRemoveEffect(target);\n\n if (targetSprite != null)\n {\n // Restore original color\n targetSprite.color = Color.white;\n }\n }\n}\npublic class AnimationCosmetic : CosmeticEffectComponent\n{\n [SerializeField] private string applyTrigger = \"BuffApplied\";\n [SerializeField] private string removeTrigger = \"BuffRemoved\";\n\n public override bool RequiresInstance => false;\n\n public override void OnApplyEffect(GameObject target)\n {\n base.OnApplyEffect(target);\n\n Animator animator = target.GetComponent<Animator>();\n if (animator != null)\n {\n animator.SetTrigger(applyTrigger);\n }\n }\n\n public override void OnRemoveEffect(GameObject target)\n {\n base.OnRemoveEffect(target);\n\n Animator animator = target.GetComponent<Animator>();\n if (animator != null)\n {\n animator.SetTrigger(removeTrigger);\n }\n }\n}\nA single effect can have multiple cosmetic components with different behaviors:
C#// PoisonEffect prefab:\n// - CosmeticEffectData\n// - PoisonParticles (RequiresInstance = true) // One per stack\n// - PoisonStatusIcon (RequiresInstance = false) // Shared UI element\n// - PoisonAudioLoop (RequiresInstance = true) // One audio loop per stack\nApplication Flow:
AttributeEffect applied to GameObjectEffectHandler checks cosmeticEffects listCosmeticEffectData:RequiresInstancing = true: Instantiate and parent to targetRequiresInstancing = false: Reuse existing instanceOnApplyEffect(target) on all componentsRemoval Flow:
EffectHandler calls OnRemoveEffect(target) on all componentsCleansUpSelf = false: EffectHandler destroys GameObject immediatelyCleansUpSelf = true: Component handles its own destructionPerformance:
RequiresInstance = false when possible (lower overhead)OnApplyEffect and OnRemoveEffect lightweightArchitecture:
OnApplyEffect, use them in OnRemoveEffectbase.OnApplyEffect() and base.OnRemoveEffect()Cleanup:
CleansUpSelf = false unless you need delayed cleanupCleansUpSelf = true, ensure you always destroy the GameObjectSpeed *= 1.5f, Duration=5, resetDurationOnReapplication=true, tag Haste.interval = 1s, maxTicks = 10, and an empty modifications array (ticks drive behaviours)PoisonDamageBehavior that applies damage during OnPeriodicTick (sample below)10s (or Infinite if the periodic schedule should drive expiry)[ \"Poisoned\" ][CreateAssetMenu(menuName = \"Combat/Effects/Poison Damage\")]\npublic sealed class PoisonDamageBehavior : EffectBehavior\n{\n [SerializeField]\n private float damagePerTick = 5f;\n\n public override void OnPeriodicTick(\n EffectBehaviorContext context,\n PeriodicEffectTickContext tickContext\n )\n {\n if (!context.Target.TryGetComponent(out PlayerHealth health))\n {\n return;\n }\n\n health.ApplyDamage(damagePerTick);\n }\n}\nPair this with a health component that owns mutable current-health state instead of modelling CurrentHealth as an Attribute.
{ attribute: \"Defense\", value: 10f }stackingMode on the effect asset to control reapplication:Stack keeps separate handles (respecting maximumStacks, trimming the oldest when the cap is reached).Refresh reuses the first handle; set resetDurationOnReapplication = true if the timer should reset on reapplication.Replace removes existing handles in the same group before adding a new one.Ignore rejects duplicate applications.stackGroup = CustomKey with a shared stackGroupKey when different assets should share a stack identity.EffectHandler.GetEffectStackCount(effect) or tag counts for debugging and UI.CosmeticEffectData, set a component\u2019s RequiresInstance = true for per\u2011application instances (e.g., particles).RequiresInstance = false for shared presenters (e.g., status icon overlay).periodicEffects list on an AttributeEffect to schedule damage/heal-over-time, resource regen, or scripted pulses without external coroutines.initialDelay, interval, and maxTicks (0 = infinite) plus its own AttributeModification bundle applied on every tick.maxTicks or when the effect handle is removed.EffectBehavior ScriptableObjects to the behaviors list for per-handle runtime logic.OnApply, OnTick (each frame), OnPeriodicTick (after periodic payloads fire), and OnRemove.OnRemove.attribute names and avoid typos.resetDurationOnReapplication = true on the effect.Instead of managing effects through inspector references or Resources.Load calls, consider using an enum-based registry for centralized, type-safe access to all your effects:
The Pattern:
C#// 1. Define an enum for all your effects\npublic enum EffectType\n{\n HastePotion,\n StrengthBuff,\n PoisonDebuff,\n ShieldBuff,\n FireDamageOverTime,\n}\n\n// 2. Create a centralized registry\npublic class EffectRegistry : ScriptableObject\n{\n [System.Serializable]\n private class EffectEntry\n {\n public EffectType type;\n public AttributeEffect effect;\n }\n\n [SerializeField] private EffectEntry[] effects;\n private Dictionary<EffectType, AttributeEffect> effectLookup;\n\n private void OnEnable()\n {\n effectLookup = effects.ToDictionary(e => e.type, e => e.effect);\n }\n\n public AttributeEffect GetEffect(EffectType type)\n {\n return effectLookup.TryGetValue(type, out AttributeEffect effect)\n ? effect\n : null;\n }\n}\n\n// 3. Usage - type-safe and refactorable\npublic class PlayerAbilities : MonoBehaviour\n{\n [SerializeField] private EffectRegistry effectRegistry;\n\n public void DrinkHastePotion()\n {\n // Compiler ensures this effect exists\n AttributeEffect haste = effectRegistry.GetEffect(EffectType.HastePotion);\n this.ApplyEffect(haste);\n\n // Typos are caught at compile time\n // effectRegistry.GetEffect(EffectType.HastPotoin); // \u274c Won't compile\n }\n}\nUsing DisplayName for Editor-Friendly Names:
C#using System.ComponentModel;\n\npublic enum EffectType\n{\n [Description(\"Haste Potion\")]\n HastePotion,\n\n [Description(\"Strength Buff (10s)\")]\n StrengthBuff,\n\n [Description(\"Poison DoT\")]\n PoisonDebuff,\n\n [Description(\"Shield (+50 Defense)\")]\n ShieldBuff,\n}\n\n// Custom PropertyDrawer can display Description in inspector\n// Or use Unity's [InspectorName] attribute in Unity 2021.2+:\n// [InspectorName(\"Haste Potion\")] HastePotion,\nCached Name Pattern for Performance:
If you're doing frequent lookups or displaying effect names in UI, cache the enum-to-string mappings:
C#public static class EffectTypeExtensions\n{\n private static readonly Dictionary<EffectType, string> DisplayNames = new()\n {\n { EffectType.HastePotion, \"Haste Potion\" },\n { EffectType.StrengthBuff, \"Strength Buff\" },\n { EffectType.PoisonDebuff, \"Poison\" },\n { EffectType.ShieldBuff, \"Shield\" },\n };\n\n public static string GetDisplayName(this EffectType type)\n {\n return DisplayNames.TryGetValue(type, out string name)\n ? name\n : type.ToString();\n }\n}\n\n// Usage in UI\nvoid UpdateEffectTooltip(EffectType effectType)\n{\n tooltipText.text = effectType.GetDisplayName();\n // No allocations, no typos, refactor-safe\n}\nBenefits:
Drawbacks:
When to Use:
When to Avoid:
Integration with Unity Helpers' Built-in Enum Utilities:
This package already includes high-performance EnumDisplayNameAttribute and ToCachedName() extensions (see EnumExtensions.cs:437-478). You can use these for better performance:
using WallstopStudios.UnityHelpers.Core.Attributes;\nusing WallstopStudios.UnityHelpers.Core.Extension;\n\npublic enum EffectType\n{\n [EnumDisplayName(\"Haste Potion\")]\n HastePotion,\n\n [EnumDisplayName(\"Strength Buff (10s)\")]\n StrengthBuff,\n\n [EnumDisplayName(\"Poison DoT\")]\n PoisonDebuff,\n}\n\n// High-performance cached display name (zero allocation after first call)\nvoid UpdateEffectTooltip(EffectType effectType)\n{\n tooltipText.text = effectType.ToDisplayName(); // Uses EnumDisplayNameCache<T>\n}\n\n// Or use ToCachedName() for the enum's field name without attributes\nvoid LogEffect(EffectType effectType)\n{\n Debug.Log($\"Applied: {effectType.ToCachedName()}\"); // Uses EnumNameCache<T>\n}\nPerformance characteristics:
ToDisplayName(): O(1) lookup, zero allocations (array-based for enums \u2264256 values)ToCachedName(): O(1) lookup, zero allocations, thread-safe with concurrent dictionaryThis eliminates the need to manually maintain a DisplayNames dictionary as shown in the earlier example\u2014the package already provides optimized caching infrastructure.
Checking for Tags:
C#// Check if effect has a specific tag\nbool hasTag = effect.HasTag(\"Haste\");\n\n// Check if effect has any of the specified tags\nbool hasAny = effect.HasAnyTag(new[] { \"Haste\", \"Speed\", \"Boost\" });\nbool hasAnyFromList = effect.HasAnyTag(myTagList); // IReadOnlyList<string> overload\nChecking for Attribute Modifications:
C#// Check if effect modifies a specific attribute\nbool modifiesSpeed = effect.ModifiesAttribute(\"Speed\");\n\n// Get all modifications for a specific attribute\nusing var lease = Buffers<AttributeModification>.List.Get(out List<AttributeModification> mods);\neffect.GetModifications(\"Speed\", mods);\nforeach (AttributeModification mod in mods)\n{\n Debug.Log($\"Action: {mod.action}, Value: {mod.value}\");\n}\nBasic Tag Queries:
C#// Check if a single tag is active\nif (player.HasTag(\"Stunned\"))\n{\n DisableInput();\n}\n\n// Check if any of the tags are active\nif (player.HasAnyTag(new[] { \"Stunned\", \"Frozen\", \"Sleeping\" }))\n{\n PreventMovement();\n}\n\n// Check if all tags are active\nif (player.HasAllTags(new[] { \"Wet\", \"Grounded\" }))\n{\n ApplyElectricShock();\n}\n\n// Check if none of the tags are active\nif (player.HasNoneOfTags(new[] { \"Invulnerable\", \"Untargetable\" }))\n{\n AllowDamage();\n}\nTag Count Queries:
C#// Get the active count for a tag\nif (player.TryGetTagCount(\"Poisoned\", out int stacks) && stacks >= 3)\n{\n TriggerCriticalPoisonWarning();\n}\n\n// Get all active tags\nList<string> activeTags = player.GetActiveTags();\nforeach (string tag in activeTags)\n{\n Debug.Log($\"Active tag: {tag}\");\n}\nCollection Type Support:
All tag query methods support multiple collection types with optimized implementations:
IReadOnlyList<string> (optimized with index-based iteration)List<string>HashSet<string>SortedSet<string>Queue<string>Stack<string>LinkedList<string>IEnumerable<string>// Example with different collection types\nHashSet<string> immunityTags = new() { \"Invulnerable\", \"Immune\" };\nif (player.HasAnyTag(immunityTags))\n{\n PreventDamage();\n}\n\nList<string> crowdControlTags = new() { \"Stunned\", \"Rooted\", \"Silenced\" };\nif (player.HasNoneOfTags(crowdControlTags))\n{\n EnableAllAbilities();\n}\nEffect State Queries:
C#// Check if a specific effect is currently active\nif (effectHandler.IsEffectActive(hasteEffect))\n{\n ShowHasteIndicator();\n}\n\n// Get the stack count for an effect\nint hasteStacks = effectHandler.GetEffectStackCount(hasteEffect);\nDebug.Log($\"Haste stacks: {hasteStacks}\");\n\n// Get remaining duration for a specific effect instance\nif (effectHandler.TryGetRemainingDuration(effectHandle, out float remaining))\n{\n UpdateDurationUI(remaining);\n}\nEffect Manipulation:
C#// Refresh an effect's duration\nif (effectHandler.RefreshEffect(effectHandle))\n{\n Debug.Log(\"Effect duration refreshed\");\n}\n\n// Refresh effect ignoring reapplication policy\neffectHandler.RefreshEffect(effectHandle, ignoreReapplicationPolicy: true);\nQ: Should I use an Attribute for CurrentHealth?
Q: Why didn't I get an EffectHandle?
null). Duration/Infinite do.Q: Do modifications stack across multiple effects?
Attribute applies all active modifications ordered by action: Addition \u2192 Multiplication \u2192 Override.Q: How do I remove just one instance of an effect?
EffectHandle returned from ApplyEffect and pass it to RemoveEffect(handle).Q: Two systems apply the same tag. Who owns removal?
Q: When should I use tags vs. checking stats?
Q: How do I check if an effect modifies a specific attribute?
effect.ModifiesAttribute(\"AttributeName\") to check if an effect contains modifications for a specific attribute, or effect.GetModifications(\"AttributeName\", buffer) to retrieve all modifications for that attribute.Q: How do I query tag counts or check multiple tags at once?
TryGetTagCount(tag, out int count) to get the active count for a tag, HasAllTags(tags) to check if all tags are active, or HasNoneOfTags(tags) to check if none are active.attribute field matches a public/private Attribute field name on an AttributesComponent subclass.Regenerate the Attribute Metadata Cache to update editor dropdowns.
Effect didn\u2019t clean up cosmetics
Confirm RequiresInstance is set correctly and components either clean up themselves (CleansUpSelf) or are destroyed by EffectHandler.
Duration didn\u2019t refresh on reapplication
resetDurationOnReapplication = true on the AttributeEffect.While the Effects System handles traditional buff/debuff mechanics well, it can also be used to build robust capability systems that drive complex gameplay decisions across your entire codebase. This section explores advanced patterns that use tags extensively for architectural purposes.
"},{"location":"features/effects/effects-system/#understanding-the-capability-pattern","title":"Understanding the Capability Pattern","text":"The Problem with Flags:
Many developers start with hardcoded boolean flags:
C#// \u274c OLD WAY: Scattered boolean flags\npublic class PlayerController : MonoBehaviour\n{\n public bool isInvulnerable;\n public bool canDash;\n public bool hasDoubleJump;\n public bool isInvisible;\n // 50+ booleans later...\n\n void TakeDamage(float damage)\n {\n if (isInvulnerable) return;\n // ...\n }\n\n void Update()\n {\n if (Input.GetKeyDown(KeyCode.Space) && canDash)\n Dash();\n }\n}\n\n// Problems:\n// 1. Every system needs direct references to check flags\n// 2. Adding temporary effects requires custom timers\n// 3. Multiple sources granting same capability = conflicts\n// 4. No centralized place to see what capabilities exist\n// 5. Difficult to debug \"why can't I do X?\"\nThe Solution - Tag-Based Capabilities:
C#// \u2705 NEW WAY: Tag-based capability system\npublic class PlayerController : MonoBehaviour\n{\n void TakeDamage(float damage)\n {\n // Any system can grant \"Invulnerable\" tag\n if (this.HasTag(\"Invulnerable\")) return;\n // ...\n }\n\n void Update()\n {\n // Check capability before allowing action\n if (Input.GetKeyDown(KeyCode.Space) && this.HasTag(\"CanDash\"))\n Dash();\n }\n}\n\n// Benefits:\n// 1. Decoupled - systems query tags, don't need direct references\n// 2. Multiple sources work automatically (reference-counted)\n// 3. Temporary effects are free - just apply/remove tag\n// 4. Debuggable - inspect TagHandler to see all active tags\n// 5. Designer-friendly - add capabilities via ScriptableObjects\n\u2705 Well-suited for:
\u274c Not ideal for:
The Problem: Many different sources need to grant invulnerability (power-ups, cutscenes, dash moves, debug mode). Without tags, you need complex logic to track all sources.
The Solution:
C#// === Setup (done once by programmer) ===\n\n// 1. Create invulnerability effects as ScriptableObjects\n// DashInvulnerability.asset:\n// - durationType: Duration (0.3 seconds)\n// - effectTags: [\"Invulnerable\", \"Dashing\"]\n// - cosmeticEffects: flash sprite white\n\n// PowerStarInvulnerability.asset:\n// - durationType: Duration (10 seconds)\n// - effectTags: [\"Invulnerable\", \"PowerStar\"]\n// - cosmeticEffects: rainbow sparkles + music\n\n// DebugInvulnerability.asset:\n// - durationType: Infinite\n// - effectTags: [\"Invulnerable\", \"Debug\"]\n// - cosmeticEffects: debug overlay\n\n// === Usage (everywhere in codebase) ===\n\n// Combat system\npublic class CombatSystem : MonoBehaviour\n{\n public void TakeDamage(GameObject target, float damage)\n {\n // One simple check - doesn't care WHY they're invulnerable\n if (target.HasTag(\"Invulnerable\"))\n {\n Debug.Log(\"Target is invulnerable!\");\n return;\n }\n\n // Apply damage...\n }\n}\n\n// Player dash ability\npublic class DashAbility : MonoBehaviour\n{\n [SerializeField] private AttributeEffect dashInvulnerability;\n\n public void Dash()\n {\n // Grant 0.3s of invulnerability during dash\n this.ApplyEffect(dashInvulnerability);\n // Automatically removed after 0.3s\n }\n}\n\n// Debug menu\npublic class DebugMenu : MonoBehaviour\n{\n [SerializeField] private AttributeEffect debugInvulnerability;\n private EffectHandle? debugHandle;\n\n public void ToggleInvulnerability()\n {\n if (debugHandle.HasValue)\n {\n player.RemoveEffect(debugHandle.Value);\n debugHandle = null;\n }\n else\n {\n debugHandle = player.ApplyEffect(debugInvulnerability);\n }\n }\n}\n\n// Cutscene controller\npublic class CutsceneController : MonoBehaviour\n{\n [SerializeField] private AttributeEffect cutsceneInvulnerability;\n private EffectHandle? cutsceneHandle;\n\n void StartCutscene()\n {\n // Prevent player from taking damage during cutscenes\n cutsceneHandle = player.ApplyEffect(cutsceneInvulnerability);\n }\n\n void EndCutscene()\n {\n if (cutsceneHandle.HasValue)\n player.RemoveEffect(cutsceneHandle.Value);\n }\n}\n\n// AI system\npublic class EnemyAI : MonoBehaviour\n{\n void ChooseTarget()\n {\n // Don't waste time attacking invulnerable targets\n List<GameObject> validTargets = allTargets\n .Where(t => !t.HasTag(\"Invulnerable\"))\n .ToList();\n\n // Attack closest valid target...\n }\n}\nWhy This Works:
Common Pitfall to Avoid:
C#// \u274c DON'T: Check multiple specific tags\nif (target.HasTag(\"DashInvulnerable\") ||\n target.HasTag(\"PowerStarInvulnerable\") ||\n target.HasTag(\"DebugInvulnerable\"))\n{\n // Now you need to update this everywhere you add a new invulnerability source!\n}\n\n// \u2705 DO: Check one general capability tag\nif (target.HasTag(\"Invulnerable\"))\n{\n // Works with all current and future invulnerability sources\n}\nThe Problem: AI needs to make decisions based on complex state (player stealth, environmental conditions, buffs, etc.). Without a unified system, you end up with brittle if/else chains.
The Solution:
C#// === Setup effects that grant capability tags ===\n\n// Stealth.asset:\n// - effectTags: [\"Invisible\", \"Stealthy\"]\n// - modifications: (none - just tags)\n\n// InWater.asset:\n// - effectTags: [\"Wet\", \"Swimming\"]\n// - modifications: Speed \u00d7 0.5\n\n// OnFire.asset:\n// - effectTags: [\"Burning\", \"OnFire\"]\n// - modifications: Health + (-5 per second)\n\n// === AI uses tags to make robust decisions ===\n\npublic class EnemyAI : MonoBehaviour\n{\n public void UpdateAI()\n {\n GameObject player = FindPlayer();\n\n // 1. Visibility checks\n if (player.HasTag(\"Invisible\"))\n {\n // Can't see invisible targets - use last known position\n PatrolToLastKnownPosition();\n return;\n }\n\n // 2. Threat assessment\n if (player.HasTag(\"Invulnerable\") && player.HasTag(\"PowerStar\"))\n {\n // Player is powered up - flee!\n Flee(player.transform.position);\n return;\n }\n\n // 3. Environmental awareness\n if (this.HasTag(\"Burning\"))\n {\n // On fire - prioritize finding water\n GameObject water = FindNearestWater();\n if (water != null)\n {\n MoveTowards(water.transform.position);\n return;\n }\n }\n\n // 4. Tactical decisions\n if (player.HasTag(\"Stunned\") || player.HasTag(\"Slowed\"))\n {\n // Player is vulnerable - aggressive pursuit\n AggressiveAttack(player);\n return;\n }\n\n // 5. Element interactions\n if (this.HasTag(\"Wet\") && player.HasTag(\"ElectricWeapon\"))\n {\n // We're wet and player has electric weapon - dangerous!\n MaintainDistance(player, minDistance: 10f);\n return;\n }\n\n // Default behavior\n ChaseAndAttack(player);\n }\n\n // Helper: Check multiple conditions easily\n bool CanEngageInCombat()\n {\n // Can't fight if we're stunned, fleeing, or in a cutscene\n return !this.HasTag(\"Stunned\") &&\n !this.HasTag(\"Fleeing\") &&\n !this.HasTag(\"InCutscene\");\n }\n}\nWhy This Works:
The Problem: Games have many gated systems (abilities, areas, features). Tracking all unlockables with individual booleans becomes unwieldy.
The Solution:
C#// === Setup unlock effects ===\n\n// UnlockDoubleJump.asset:\n// - durationType: Infinite (permanent unlock)\n// - effectTags: [\"CanDoubleJump\", \"HasUpgrade\"]\n\n// QuestKeyItem.asset:\n// - durationType: Infinite\n// - effectTags: [\"HasKeyItem\", \"CanEnterDungeon\"]\n\n// TutorialComplete.asset:\n// - durationType: Infinite\n// - effectTags: [\"TutorialComplete\", \"CanAccessMultiplayer\"]\n\n// === Usage throughout game systems ===\n\n// Ability system\npublic class PlayerAbilities : MonoBehaviour\n{\n void Update()\n {\n // Jump\n if (Input.GetKeyDown(KeyCode.Space))\n {\n if (isGrounded)\n {\n Jump();\n }\n // Double jump only works if unlocked\n else if (this.HasTag(\"CanDoubleJump\") && !hasUsedDoubleJump)\n {\n Jump();\n hasUsedDoubleJump = true;\n }\n }\n\n // Dash\n if (Input.GetKeyDown(KeyCode.LeftShift))\n {\n if (this.HasTag(\"CanDash\"))\n {\n Dash();\n }\n else\n {\n ShowMessage(\"Unlock dash ability first!\");\n }\n }\n }\n}\n\n// Level gate\npublic class DungeonGate : MonoBehaviour\n{\n void OnTriggerEnter2D(Collider2D other)\n {\n GameObject player = other.gameObject;\n\n if (player.HasTag(\"HasKeyItem\"))\n {\n // Has the key - open gate\n OpenGate();\n }\n else\n {\n // Missing key - show hint\n ShowMessage(\"You need the Ancient Key to enter.\");\n }\n }\n}\n\n// UI system\npublic class MainMenuUI : MonoBehaviour\n{\n [SerializeField] private Button multiplayerButton;\n\n void Update()\n {\n // Disable multiplayer until tutorial is complete\n multiplayerButton.interactable = player.HasTag(\"TutorialComplete\");\n }\n}\n\n// Save system\npublic class SaveSystem : MonoBehaviour\n{\n public SaveData CreateSaveData(GameObject player)\n {\n // Save all permanent unlocks\n var saveData = new SaveData\n {\n unlockedAbilities = new List<string>()\n };\n\n // Check all capability tags\n if (player.HasTag(\"CanDoubleJump\"))\n saveData.unlockedAbilities.Add(\"DoubleJump\");\n\n if (player.HasTag(\"CanDash\"))\n saveData.unlockedAbilities.Add(\"Dash\");\n\n if (player.HasTag(\"HasKeyItem\"))\n saveData.unlockedAbilities.Add(\"KeyItem\");\n\n return saveData;\n }\n\n public void LoadSaveData(GameObject player, SaveData saveData)\n {\n // Reapply permanent unlocks\n foreach (string ability in saveData.unlockedAbilities)\n {\n AttributeEffect unlock = LoadUnlockEffect(ability);\n player.ApplyEffect(unlock);\n }\n }\n}\nWhy This Works:
The Problem: Complex element systems (wet + electric = shock, burning + ice = extinguish) require tracking multiple states and their interactions.
The Solution:
C#// === Setup element effects ===\n\n// Wet.asset:\n// - durationType: Duration (10 seconds)\n// - effectTags: [\"Wet\", \"ConductsElectricity\"]\n// - cosmeticEffects: water drips\n\n// Burning.asset:\n// - durationType: Duration (5 seconds)\n// - effectTags: [\"Burning\", \"OnFire\"]\n// - modifications: Health + (-5 per second)\n// - cosmeticEffects: fire particles\n\n// Frozen.asset:\n// - durationType: Duration (3 seconds)\n// - effectTags: [\"Frozen\", \"Immobilized\"]\n// - modifications: Speed \u00d7 0\n\n// Electrified.asset:\n// - durationType: Duration (4 seconds)\n// - effectTags: [\"Electrified\", \"Stunned\"]\n// - modifications: Speed \u00d7 0\n\n// === Interaction system ===\n\npublic class ElementalInteractions : MonoBehaviour\n{\n [SerializeField] private AttributeEffect wetEffect;\n [SerializeField] private AttributeEffect burningEffect;\n [SerializeField] private AttributeEffect frozenEffect;\n [SerializeField] private AttributeEffect electrifiedEffect;\n\n public void OnEnvironmentalEffect(GameObject target, string effectType)\n {\n switch (effectType)\n {\n case \"Water\":\n // Apply wet\n target.ApplyEffect(wetEffect);\n\n // Water puts out fire\n if (target.HasTag(\"Burning\"))\n {\n target.RemoveEffects(target.GetHandlesWithTag(\"Burning\"));\n CreateSteamParticles(target.transform.position);\n }\n break;\n\n case \"Fire\":\n // Fire dries wet targets\n if (target.HasTag(\"Wet\"))\n {\n target.RemoveEffects(target.GetHandlesWithTag(\"Wet\"));\n CreateSteamParticles(target.transform.position);\n }\n else\n {\n // Set on fire if dry\n target.ApplyEffect(burningEffect);\n }\n break;\n\n case \"Ice\":\n // Ice freezes wet targets (stronger effect)\n if (target.HasTag(\"Wet\"))\n {\n target.ApplyEffect(frozenEffect);\n target.RemoveEffects(target.GetHandlesWithTag(\"Wet\"));\n }\n break;\n\n case \"Electric\":\n // Electric shocks wet targets\n if (target.HasTag(\"Wet\"))\n {\n // Extra damage and stun\n target.ApplyEffect(electrifiedEffect);\n target.TakeDamage(20f); // Bonus damage\n CreateElectricParticles(target.transform.position);\n }\n break;\n }\n }\n\n public float CalculateElementalDamageMultiplier(GameObject attacker, GameObject target)\n {\n float multiplier = 1f;\n\n // Fire does extra damage to frozen targets (they thaw)\n if (attacker.HasTag(\"FireWeapon\") && target.HasTag(\"Frozen\"))\n multiplier *= 1.5f;\n\n // Electric does massive damage to wet targets\n if (attacker.HasTag(\"ElectricWeapon\") && target.HasTag(\"Wet\"))\n multiplier *= 2.0f;\n\n // Ice does extra damage to burning targets (extinguish)\n if (attacker.HasTag(\"IceWeapon\") && target.HasTag(\"Burning\"))\n multiplier *= 1.5f;\n\n return multiplier;\n }\n}\nWhy This Works:
The Problem: Traditional state machines become complex with many states and transitions. Tags can represent state more flexibly.
Traditional Approach:
C#// \u274c OLD WAY: Rigid state machine\npublic enum PlayerState\n{\n Idle,\n Walking,\n Running,\n Jumping,\n Attacking,\n Stunned,\n // What if player is jumping AND attacking?\n // What if player is attacking AND stunned?\n // Need combinatorial explosion of states!\n}\n\nprivate PlayerState currentState;\n\nvoid Update()\n{\n switch (currentState)\n {\n case PlayerState.Stunned:\n // Can't do anything when stunned\n return;\n\n case PlayerState.Attacking:\n // Can't move while attacking\n // But what if we want to allow movement during some attacks?\n break;\n\n // 50 more cases...\n }\n}\nTag-Based Approach:
C#// \u2705 NEW WAY: Flexible tag-based state\nvoid Update()\n{\n // States can overlap naturally\n bool isGrounded = CheckGrounded();\n bool isMoving = Input.GetAxis(\"Horizontal\") != 0;\n\n // Check capabilities, not rigid states\n if (this.HasTag(\"Stunned\") || this.HasTag(\"Frozen\"))\n {\n // Can't act while crowd-controlled\n return;\n }\n\n // Movement\n if (isMoving && !this.HasTag(\"Immobilized\"))\n {\n Move();\n\n // Can attack while moving (if not attacking already)\n if (Input.GetButtonDown(\"Fire1\") && !this.HasTag(\"Attacking\"))\n {\n Attack();\n }\n }\n\n // Jumping\n if (Input.GetButtonDown(\"Jump\") && isGrounded)\n {\n if (this.HasTag(\"CanJump\") && !this.HasTag(\"Jumping\"))\n {\n Jump();\n }\n }\n\n // Special abilities\n if (Input.GetButtonDown(\"Dash\"))\n {\n if (this.HasTag(\"CanDash\") && !this.HasTag(\"Dashing\"))\n {\n Dash();\n }\n }\n}\n\n// Actions apply tags to themselves\nvoid Attack()\n{\n // Apply \"Attacking\" tag for duration of attack\n this.ApplyEffect(attackingEffect); // 0.5s duration\n // Play animation...\n}\n\nvoid Dash()\n{\n // Apply multiple tags during dash\n this.ApplyEffect(dashingEffect);\n // Effect grants: [\"Dashing\", \"Invulnerable\", \"FastMovement\"]\n // All removed automatically after duration\n}\nWhy This Works:
The Problem: Debug tools and cheat codes need to temporarily grant capabilities without affecting production code.
The Solution:
C#public class DebugConsole : MonoBehaviour\n{\n [SerializeField] private AttributeEffect godModeEffect;\n [SerializeField] private AttributeEffect noclipEffect;\n [SerializeField] private AttributeEffect unlockAllEffect;\n\n private Dictionary<string, EffectHandle?> activeDebugEffects = new();\n\n void Update()\n {\n // God mode (invulnerable + infinite resources)\n if (Input.GetKeyDown(KeyCode.F1))\n {\n ToggleDebugEffect(\"GodMode\", godModeEffect);\n }\n\n // Noclip (fly through walls)\n if (Input.GetKeyDown(KeyCode.F2))\n {\n ToggleDebugEffect(\"Noclip\", noclipEffect);\n }\n\n // Unlock all abilities\n if (Input.GetKeyDown(KeyCode.F3))\n {\n ApplyDebugEffect(\"UnlockAll\", unlockAllEffect);\n }\n }\n\n void ToggleDebugEffect(string name, AttributeEffect effect)\n {\n if (activeDebugEffects.TryGetValue(name, out EffectHandle? handle) && handle.HasValue)\n {\n player.RemoveEffect(handle.Value);\n activeDebugEffects.Remove(name);\n Debug.Log($\"Debug: {name} OFF\");\n }\n else\n {\n EffectHandle? newHandle = player.ApplyEffect(effect);\n activeDebugEffects[name] = newHandle;\n Debug.Log($\"Debug: {name} ON\");\n }\n }\n\n void ApplyDebugEffect(string name, AttributeEffect effect)\n {\n player.ApplyEffect(effect);\n Debug.Log($\"Debug: Applied {name}\");\n }\n}\n\n// GodMode.asset:\n// - durationType: Infinite\n// - effectTags: [\"Invulnerable\", \"InfiniteResources\", \"Debug\"]\n// - modifications: Health \u00d7 999, Stamina \u00d7 999\n\n// Noclip.asset:\n// - durationType: Infinite\n// - effectTags: [\"Noclip\", \"Flying\", \"Debug\"]\n// - cosmeticEffects: ghost transparency\n\n// UnlockAll.asset:\n// - durationType: Infinite\n// - effectTags: [\"CanDoubleJump\", \"CanDash\", \"CanWallJump\", \"Debug\"]\nWhy This Works:
When to Use Tags vs Attributes:
Use Case Solution Example Binary state Tag \"Invulnerable\", \"CanDash\" Numeric value Attribute Health, Speed, Damage Temporary state Tag with Duration \"Stunned\" for 3 seconds Stacking bonuses Attribute with Multiplication Speed \u00d7 1.5 from multiple haste effects Category membership Tag \"Enemy\", \"Friendly\", \"Neutral\" Resource management Attribute Stamina, Mana Permission/unlock Tag with Infinite duration \"CanEnterDungeon\", \"TutorialComplete\" Complex interactions Multiple Tags \"Wet\" + \"Electrified\" = shocked"},{"location":"features/effects/effects-system/#best-practices-for-capability-systems","title":"Best Practices for Capability Systems","text":"// \u2705 Good: Clear categories\n\"Status_Stunned\"\n\"Ability_CanDash\"\n\"Quest_HasKeyItem\"\n\"Element_Burning\"\n\n// \u274c Bad: Ambiguous\n\"Stunned\" // Status or ability?\n\"Fire\" // On fire or has fire weapon?\npublic static class GameplayTags\n{\n // States\n public const string Invulnerable = \"Invulnerable\";\n public const string Stunned = \"Stunned\";\n public const string Invisible = \"Invisible\";\n\n // Capabilities\n public const string CanDash = \"CanDash\";\n public const string CanDoubleJump = \"CanDoubleJump\";\n\n // Elements\n public const string Burning = \"Burning\";\n public const string Wet = \"Wet\";\n public const string Frozen = \"Frozen\";\n}\n\n// Usage\nif (player.HasTag(GameplayTags.Invulnerable))\n{\n // Compiler will catch typos!\n}\n/// Tags Registry\n/// ===================================\n/// Invulnerable - Cannot take damage from any source\n/// Stunned - Cannot perform any actions (move, attack, cast)\n/// InCombat - Currently engaged in combat (prevents resting, saving)\n/// Invisible - Cannot be seen by AI or targeted\n/// CanDash - Has unlocked dash ability\n/// CanDoubleJump - Has unlocked double jump ability\n/// Wet - Conducts electricity, prevents fire, can be frozen\n/// Burning - Takes fire damage over time, can ignite others\n// effectTags serve multiple purposes:\n// - Internal organization (removable via GetHandlesWithTag + RemoveEffects)\n// - Gameplay queries (checked via HasTag)\n// - Effect identification and categorization\n\n// Example effect:\n// HastePotion.asset:\n// - effectTags: [\"Haste\", \"Potion\", \"Buff\", \"MovementBuff\"]\n// - Use \"Haste\" for gameplay queries (player.HasTag(\"Haste\"))\n// - Use \"Potion\" for finding/removing all potions\n// - Use \"Buff\" for UI categorization\n[Test]\npublic void TestInvulnerability_MultipleSourcesStack()\n{\n GameObject player = CreateTestPlayer();\n\n // Apply invulnerability from two sources\n EffectHandle? dash = player.ApplyEffect(dashInvulnerability);\n EffectHandle? powerup = player.ApplyEffect(powerupInvulnerability);\n\n Assert.IsTrue(player.HasTag(\"Invulnerable\"));\n\n // Remove one source - should still be invulnerable\n player.RemoveEffect(dash.Value);\n Assert.IsTrue(player.HasTag(\"Invulnerable\"));\n\n // Remove second source - now vulnerable\n player.RemoveEffect(powerup.Value);\n Assert.IsFalse(player.HasTag(\"Invulnerable\"));\n}\nIReadOnlyList<string> overloads in hot paths.Related:
Execute methods from the inspector with one click.
The [WButton] attribute exposes methods as clickable buttons in the Unity inspector, complete with result history, async support, cancellation, custom styling, and automatic grouping. Test gameplay features, debug systems, and prototype rapidly without writing custom editors.
using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class PlayerController : MonoBehaviour\n{\n public int health = 100;\n\n [WButton(\"Heal Player\")]\n private void Heal()\n {\n health = 100;\n Debug.Log(\"Player healed!\");\n }\n\n [WButton(\"Take Damage\")]\n private void TakeDamage()\n {\n health -= 10;\n Debug.Log($\"Player took damage! Health: {health}\");\n }\n}\nThe [WButton] attribute accepts several optional parameters to customize button appearance, behavior, and organization.
[WButton(\n string displayName = null,\n int drawOrder = 0,\n int historyCapacity = WButtonAttribute.UseGlobalHistory,\n string colorKey = null,\n string groupName = null,\n int groupPriority = WButtonAttribute.NoGroupPriority,\n WButtonGroupPlacement groupPlacement = WButtonGroupPlacement.UseGlobalSetting\n)]\nControls the text shown on the button in the inspector.
\"RollDice\" for RollDice())// Without displayName - shows \"SpawnEnemy\"\n[WButton]\nprivate void SpawnEnemy() { }\n\n// With displayName - shows \"\ud83d\udd2b Spawn Enemy\"\n[WButton(\"\ud83d\udd2b Spawn Enemy\")]\nprivate void SpawnEnemy1() { }\n\n// More descriptive labels\n[WButton(\"Reset Player to Checkpoint\")]\nprivate void ResetPlayer() { }\n\n[WButton(\"Clear All Save Data\")]\nprivate void ClearSaveData() { }\nControls the sort order of buttons within their placement section (top or bottom).
groupPlacement to control whether buttons appear above or below propertiespublic class PlayerController1 : MonoBehaviour\n{\n public int health = 100;\n public float speed = 5f;\n\n // These buttons render in order: Initialize, Validate, Debug Info\n // Placement (above/below properties) is controlled by groupPlacement or global settings\n [WButton(\"Initialize\", drawOrder: -1)]\n private void Initialize() { }\n\n [WButton(\"Validate\", drawOrder: 0)]\n private void Validate() { }\n\n [WButton(\"Debug Info\", drawOrder: 1)]\n private void ShowDebugInfo() { }\n}\nVisual layout:
"},{"location":"features/inspector/inspector-button/#historycapacity-int-optional","title":"historyCapacity (int, optional)","text":"Controls how many previous results are stored for methods that return values.
WButtonAttribute.UseGlobalHistory (uses project setting, typically 5)1 to 10 results, or -1 for global defaultvoid methods (no history stored)// Use global setting (default: 5 results)\n[WButton(\"Roll Dice\")]\nprivate int RollDice() => Random.Range(1, 7);\n\n// Store only last result\n[WButton(\"Get Timestamp\", historyCapacity: 1)]\nprivate string GetTimestamp() => DateTime.Now.ToString();\n\n// Store up to 10 results for detailed history\n[WButton(\"Measure Frame Time\", historyCapacity: 10)]\nprivate float MeasureFrameTime() => Time.deltaTime * 1000f;\n\n// Disable history completely (1 = minimum)\n[WButton(\"Ping Server\", historyCapacity: 1)]\nprivate async Task<string> PingServerAsync(CancellationToken ct)\n{\n // ... ping logic\n return \"Pong!\";\n}\nPerformance tip: Use lower values (1-3) for methods called frequently to reduce memory usage.
Applies custom color themes to buttons using predefined color keys.
null (uses default button color)\"Default\", \"Default-Light\", \"Default-Dark\", or custom keys// Default blue button\n[WButton(\"Standard Action\")]\nprivate void StandardAction() { }\n\n// Custom themed button (requires setup in project settings)\n[WButton(\"Dangerous Action\", colorKey: \"Danger\")]\nprivate void DangerousAction() { }\n\n[WButton(\"Success Action\", colorKey: \"Success\")]\nprivate void SuccessAction() { }\n\n[WButton(\"Warning Action\", colorKey: \"Warning\")]\nprivate void WarningAction() { }\nSetting up custom colors:
\"Danger\")[WButton] attributeOrganizes buttons under labeled group headers.
null (no group header)groupName are merged into a single groupgroupPlacement and groupPriority to control where groups appearpublic class GameManager : MonoBehaviour\n{\n // \"Debug Tools\" group - will appear based on groupPlacement or global settings\n [WButton(\"Log State\", groupName: \"Debug Tools\", groupPlacement: WButtonGroupPlacement.Top)]\n private void LogState() { }\n\n [WButton(\"Clear Console\", groupName: \"Debug Tools\")]\n private void ClearConsole() { }\n\n // Inspector properties here\n public int currentLevel = 1;\n public bool debugMode = false;\n\n // \"Save System\" group - explicitly placed at bottom\n [WButton(\"Save Game\", groupName: \"Save System\", groupPlacement: WButtonGroupPlacement.Bottom)]\n private void SaveGame() { }\n\n [WButton(\"Load Game\", groupName: \"Save System\")]\n private void LoadGame() { }\n\n [WButton(\"Delete Save\", groupName: \"Save System\")]\n private void DeleteSave() { }\n}\nNotes:
Controls the render order of button groups within a placement section.
WButtonAttribute.NoGroupPriority (renders after groups with explicit priorities)groupName; ungrouped buttons ignore this valuepublic class ActionPanel : MonoBehaviour\n{\n // This group renders FIRST (priority 0)\n [WButton(\"Quick Save\", groupName: \"Primary\", groupPriority: 0)]\n private void QuickSave() { }\n\n [WButton(\"Quick Load\", groupName: \"Primary\", groupPriority: 0)]\n private void QuickLoad() { }\n\n // This group renders SECOND (priority 10)\n [WButton(\"Debug Info\", groupName: \"Debug\", groupPriority: 10)]\n private void ShowDebugInfo() { }\n\n // This group renders LAST (no explicit priority)\n [WButton(\"Reset\", groupName: \"Misc\")]\n private void Reset() { }\n}\nImportant: The first declared button in a group sets the canonical priority for the entire group. If other buttons in the same group specify different priorities, they are ignored and a warning is displayed in the inspector.
C#// \u26a0\ufe0f WARNING: Conflicting priorities in the same group\n[WButton(\"Action A\", groupName: \"Tools\", groupPriority: 0)] // This priority is used\nprivate void ActionA() { }\n\n[WButton(\"Action B\", groupName: \"Tools\", groupPriority: 10)] // Ignored! Warning shown\nprivate void ActionB() { }\nControls where a button group renders, overriding the global Unity Helpers setting.
WButtonGroupPlacement.UseGlobalSettingUseGlobalSetting \u2014 Respects the global setting in Project SettingsTop \u2014 Always render above inspector propertiesBottom \u2014 Always render below inspector propertiesgroupName; ungrouped buttons ignore this valuepublic class MixedPlacementExample : MonoBehaviour\n{\n public int health = 100;\n public float speed = 5f;\n\n // This group ALWAYS renders at the top, regardless of global setting\n [WButton(\"Initialize\", groupName: \"Setup\", groupPlacement: WButtonGroupPlacement.Top)]\n private void Initialize() { }\n\n [WButton(\"Validate\", groupName: \"Setup\", groupPlacement: WButtonGroupPlacement.Top)]\n private void Validate() { }\n\n // Properties appear here (health, speed)\n\n // This group ALWAYS renders at the bottom, regardless of global setting\n [WButton(\"Cleanup\", groupName: \"Maintenance\", groupPlacement: WButtonGroupPlacement.Bottom)]\n private void Cleanup() { }\n\n [WButton(\"Reset All\", groupName: \"Maintenance\", groupPlacement: WButtonGroupPlacement.Bottom)]\n private void ResetAll() { }\n}\nImportant: Like groupPriority, the first declared button in a group sets the canonical placement for the entire group. Conflicting values from other buttons in the same group are ignored with a warning.
Use both parameters together for fine-grained control:
C#using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\n[CreateAssetMenu(\n fileName = \"AdvancedButtonLayout\",\n menuName = \"Wallstop Studios/Advanced Button Layout\"\n)]\npublic class AdvancedButtonLayout : ScriptableObject\n{\n // TOP SECTION - ordered by priority\n [WButton(\n \"Validate Data\",\n groupName: \"Validation\",\n groupPriority: 1,\n groupPlacement: WButtonGroupPlacement.Top\n )]\n private void ValidateData() { }\n\n [WButton(\n \"Generate IDs\",\n groupName: \"Authoring\",\n groupPriority: 0,\n groupPlacement: WButtonGroupPlacement.Top\n )]\n private void GenerateIds() { }\n\n // Properties appear here\n\n public int property1;\n public string property2;\n\n // BOTTOM SECTION - ordered by priority\n\n [WButton(\n \"Submit to Server\",\n groupName: \"Network\",\n groupPriority: 10,\n groupPlacement: WButtonGroupPlacement.Bottom\n )]\n private void Submit() { }\n\n [WButton(\n \"Export\",\n groupName: \"IO\",\n groupPriority: 0,\n groupPlacement: WButtonGroupPlacement.Bottom\n )]\n private void Export() { }\n\n [WButton(\n \"Import\",\n groupName: \"IO\",\n groupPriority: 0,\n groupPlacement: WButtonGroupPlacement.Bottom\n )]\n private void Import() { }\n}\nRendering Order:
groupPriority):groupPriority):using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class LevelManager : MonoBehaviour\n{\n public int currentLevel = 1;\n public bool debugMode = false;\n\n // Setup group - explicitly placed at top, renders first due to groupPriority: 0\n [WButton(\"Initialize Level\", groupName: \"Setup\", groupPriority: 0, groupPlacement: WButtonGroupPlacement.Top)]\n private void Initialize()\n {\n Debug.Log(\"Level initialized!\");\n }\n\n [WButton(\"\u2713 Validate Configuration\", groupName: \"Setup\")]\n private void ValidateConfig()\n {\n Debug.Log(\"Configuration valid!\");\n }\n\n // Debug group - explicitly placed at top, renders second due to groupPriority: 1\n [WButton(\"Roll Dice\", historyCapacity: 10, groupName: \"Debug\", groupPriority: 1, groupPlacement: WButtonGroupPlacement.Top)]\n private int RollDice() => Random.Range(1, 7);\n\n [WButton(\"\ud83c\udfaf Spawn Test Enemy\", colorKey: \"Warning\", groupName: \"Debug\")]\n private void SpawnTestEnemy()\n {\n // Spawn logic here\n }\n\n // Properties appear here in the inspector\n\n // Actions group - explicitly placed at bottom, renders first in bottom section due to groupPriority: 0\n [WButton(\"\u25b6 Start Level\", colorKey: \"Success\", groupName: \"Actions\", groupPriority: 0, groupPlacement: WButtonGroupPlacement.Bottom)]\n private void StartLevel()\n {\n Debug.Log($\"Starting level {currentLevel}...\");\n }\n\n [WButton(\"\u23f8 Pause Game\", groupName: \"Actions\")]\n private void PauseGame()\n {\n Time.timeScale = 0f;\n }\n\n [WButton(\"\ud83d\udd04 Restart Level\", colorKey: \"Danger\", groupName: \"Actions\")]\n private void RestartLevel()\n {\n // Restart logic here\n }\n\n // Maintenance group - explicitly placed at bottom, renders last in bottom section due to groupPriority: 10\n [WButton(\"Clear Cache\", historyCapacity: 1, groupName: \"Maintenance\", groupPriority: 10, groupPlacement: WButtonGroupPlacement.Bottom)]\n private string ClearCache()\n {\n return $\"Cache cleared at {System.DateTime.Now:HH:mm:ss}\";\n }\n}\nWButton supports four method signatures:
"},{"location":"features/inspector/inspector-button/#1-void-methods-immediate","title":"1. Void Methods (Immediate)","text":"C#[WButton(\"Log Message\")]\nprivate void LogMessage()\n{\n Debug.Log(\"Button clicked!\");\n}\nBehavior: Executes immediately, no return value shown
"},{"location":"features/inspector/inspector-button/#2-returning-values-with-history","title":"2. Returning Values (With History)","text":"C#[WButton(\"Roll Dice\", historyCapacity: 10, groupName: \"Debug\")]\nprivate int RollDice()\n{\n return Random.Range(1, 7);\n}\n\n[WButton(\"Get Position\")]\nprivate Vector3 GetPlayerPosition()\n{\n return transform.position;\n}\nBehavior: Shows return value in a collapsible history panel
"},{"location":"features/inspector/inspector-button/#3-coroutines-ienumerator","title":"3. Coroutines (IEnumerator)","text":"C#[WButton(\"Fade Out\")]\nprivate IEnumerator FadeOut()\n{\n SpriteRenderer sprite = GetComponent<SpriteRenderer>();\n Color color = sprite.color;\n\n for (float t = 1f; t >= 0f; t -= Time.deltaTime)\n {\n color.a = t;\n sprite.color = color;\n yield return null;\n }\n\n Debug.Log(\"Fade complete!\");\n}\nBehavior:
using System.Threading;\nusing System.Threading.Tasks;\n\n[WButton(\"Load Data\")]\nprivate async Task<string> LoadDataAsync(CancellationToken ct)\n{\n Debug.Log(\"Loading...\");\n await Task.Delay(2000, ct); // Simulate async work\n return \"Data loaded successfully!\";\n}\n\n[WButton(\"Download Asset\")]\nprivate async ValueTask<Texture2D> DownloadAssetAsync(CancellationToken ct)\n{\n Debug.Log(\"Downloading...\");\n await Task.Delay(1000, ct);\n // Simulate download\n return new Texture2D(256, 256);\n}\nBehavior:
CancellationToken injection (optional parameter)Cancellation Example:
C#[WButton(\"Long Operation\")]\nprivate async Task LongOperationAsync(CancellationToken ct)\n{\n for (int i = 0; i < 10; i++)\n {\n ct.ThrowIfCancellationRequested(); // Check cancellation\n Debug.Log($\"Step {i + 1}/10\");\n await Task.Delay(500, ct);\n }\n return Task.CompletedTask;\n}\nSupported Signatures:
Task (void async)Task<T> (async with a result)ValueTask (void async, no heap allocation)ValueTask<T> (async with a result, no heap allocation)[WButton(\"Generate ID\", historyCapacity: 10)]\nprivate string GenerateId()\n{\n return System.Guid.NewGuid().ToString().Substring(0, 8);\n}\nFeatures:
// Use global setting (default: 5, configurable in UnityHelpersSettings)\n[WButton(\"Use Global\")]\nprivate int UseGlobal() => Random.Range(1, 100);\n\n// Custom capacity per method\n[WButton(\"Keep 20 Results\", historyCapacity: 20)]\nprivate float KeepMany() => Random.value;\n\n// Disable history (0 capacity)\n[WButton(\"No History\", historyCapacity: 0)]\nprivate void NoHistory() => Debug.Log(\"No history stored\");\nGlobal Setting: UnityHelpersSettings.WButtonHistorySize (default: 5, range: 1-10)
"},{"location":"features/inspector/inspector-button/#draw-order-positioning","title":"Draw Order & Positioning","text":"
Control the sort order of buttons within their placement section:
C#public class ButtonPositioning : MonoBehaviour\n{\n // Buttons are sorted by drawOrder (lower values first)\n [WButton(\"Top Button\", drawOrder: -1)]\n private void TopButton() => Debug.Log(\"Renders first (lowest drawOrder)\");\n\n [WButton(\"Middle Button\", drawOrder: 0)]\n private void MiddleButton() => Debug.Log(\"Renders second\");\n\n [WButton(\"Bottom Button\", drawOrder: 1)]\n private void BottomButton() => Debug.Log(\"Renders last (highest drawOrder)\");\n\n // Inspector fields - buttons appear above or below based on groupPlacement/global settings\n public int someField = 10;\n}\nPositioning Rules:
drawOrder values render first within a placement sectiongroupPlacement or the global WButtonPlacement setting, not by drawOrderdrawOrder, buttons render in declaration order (source code order)[WButton(drawOrder: 0)]\nprivate void Action1() {}\n\n[WButton( drawOrder: 0)]\nprivate void Action2() {}\n\n// ... 10 more buttons with drawOrder: 0 ...\n\n[WButton(drawOrder: 0)]\nprivate void Action12() {}\nPagination Settings:
UnityHelpersSettings.WButtonPageSize (default: 6)Organize buttons into named sections:
C#[WButton(\"Spawn Enemy\", groupName: \"Combat\")]\nprivate void SpawnEnemy() => Debug.Log(\"Enemy spawned\");\n\n[WButton(\"Clear Enemies\", groupName: \"Combat\")]\nprivate void ClearEnemies() => Debug.Log(\"Enemies cleared\");\n\n[WButton(\"Save Game\", groupName: \"Persistence\")]\nprivate void SaveGame() => Debug.Log(\"Game saved\");\n\n[WButton(\"Load Game\", groupName: \"Persistence\")]\nprivate void LoadGame() => Debug.Log(\"Game loaded\");\nGrouping Behavior:
groupNamedrawOrderUnityHelpersSettings.WButtonFoldoutBehavior)Global Setting: UnityHelpersSettings.WButtonFoldoutBehavior
Options:
Always - Always show group foldout trianglesStartExpanded - Collapsible, starts openStartCollapsed - Collapsible, starts closedAnimation:
UnityHelpersSettings.WButtonFoldoutTweenEnabledUnityHelpersSettings.WButtonFoldoutSpeed (default: 2.0, range: 2-12)[WButton(\"Dangerous Action\", colorKey: \"Default-Dark\")]\nprivate void DangerousAction() => Debug.LogWarning(\"Dangerous!\");\n\n[WButton(\"Safe Action\", colorKey: \"Default-Light\")]\nprivate void SafeAction() => Debug.Log(\"Safe operation\");\nBuilt-in Priorities (Color Keys):
\"Default\" - Theme-aware (adapts to Unity theme)\"Default-Dark\" - Dark theme colors\"Default-Light\" - Light theme colors\"WDefault\" - Legacy vibrant blueUnityHelpersSettings.WButtonCustomColorsDefine Custom Colors:
ProjectSettings/UnityHelpersSettings.assetWButtonCustomColors dictionaryAll buttons respect project-wide settings defined in UnityHelpersSettings:
Location: ProjectSettings/UnityHelpersSettings.asset
Settings:
WButtonHistorySize (default: 5, range: 1-10) - Results to keep per methodWButtonPlacement (Top or Bottom) - Default button positionWButtonFoldoutBehavior (Always, StartExpanded, StartCollapsed) - Group collapsibilityWButtonFoldoutTweenEnabled (bool) - Enable group animationsWButtonFoldoutSpeed (default: 2.0, range: 2-12) - Animation speedWButtonPageSize (default: 6) - Buttons per page for paginationWButtonCustomColors - Custom color palette dictionary// \u2705 GOOD: Action-oriented, descriptive\n[WButton(\"Heal to Full\")]\nprivate void HealToFull() { ... }\n\n[WButton(\"Spawn 10 Enemies\")]\nprivate void SpawnEnemies() { ... }\n\n// \u274c BAD: Vague or technical\n[WButton(\"DoStuff\")]\nprivate void DoStuff() { ... }\n\n[WButton] // Defaults to method name \"HandlePlayerDeath\"\nprivate void HandlePlayerDeath() { ... }\n// \u2705 GOOD: Grouped by feature\n[WButton(\"Spawn Enemy\", groupName: \"Combat Testing\")]\nprivate void SpawnEnemy() { ... }\n\n[WButton(\"Kill All Enemies\", groupName: \"Combat Testing\")]\nprivate void KillAll() { ... }\n\n[WButton(\"Save Progress\", groupName: \"Persistence\")]\nprivate void Save() { ... }\n\n// \u274c BAD: No grouping, cluttered inspector\n[WButton(\"Spawn Enemy\")]\nprivate void SpawnEnemy() { ... }\n\n[WButton(\"Save Progress\")]\nprivate void Save() { ... }\n\n[WButton(\"Kill All Enemies\")]\nprivate void KillAll() { ... }\n// \u2705 GOOD: History helps track random values\n[WButton(\"Roll Loot\", historyCapacity: 10)]\nprivate string RollLoot()\n{\n return lootTable[PRNG.Instance.Next(0, lootTable.Length)];\n}\n\n// \u2705 GOOD: No history needed for fixed actions\n[WButton(\"Reset Position\", historyCapacity: 0)]\nprivate void ResetPosition()\n{\n transform.position = Vector3.zero;\n}\n// \u2705 GOOD: Accept CancellationToken, check it\n[WButton(\"Long Task\")]\nprivate async Task LongTaskAsync(CancellationToken ct)\n{\n for (int i = 0; i < 100; i++)\n {\n ct.ThrowIfCancellationRequested();\n await Task.Delay(100, ct);\n }\n}\n\n// \u2705 GOOD: Handle exceptions gracefully\n[WButton(\"Risky Operation\")]\nprivate async Task RiskyOperationAsync()\n{\n try\n {\n await SomeRiskyApiCall();\n }\n catch (Exception ex)\n {\n Debug.LogError($\"Operation failed: {ex.Message}\");\n }\n}\n\n// \u274c BAD: Long operation with no cancellation support\n[WButton(\"Infinite Loop\")]\nprivate async Task InfiniteLoopAsync()\n{\n while (true) // No way to stop this!\n {\n await Task.Delay(1000);\n }\n}\n// \u2705 GOOD: Use colors to indicate risk/importance\n[WButton(\"Delete All Data\", colorKey: \"Default-Dark\")] // Dark = danger\nprivate void DeleteAllData() { ... }\n\n[WButton(\"Quick Save\", colorKey: \"Default-Light\")] // Light = safe\nprivate void QuickSave() { ... }\n\n// \u274c BAD: Random colors without meaning\n[WButton(\"Log Message\", colorKey: \"CustomPurple\")] // Why purple?\nprivate void LogMessage() { ... }\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class PlayerDebug : MonoBehaviour\n{\n public int health = 100;\n public int gold = 0;\n\n [WButton(\"Heal\", groupName: \"Health\", colorKey: \"Default-Light\")]\n private void Heal()\n {\n health = 100;\n Debug.Log(\"Player healed!\");\n }\n\n [WButton(\"Take Damage\", groupName: \"Health\")]\n private void TakeDamage()\n {\n health -= 25;\n Debug.Log($\"Took damage! Health: {health}\");\n }\n\n [WButton(\"Kill Player\", groupName: \"Health\", colorKey: \"Default-Dark\")]\n private void Kill()\n {\n health = 0;\n Debug.LogWarning(\"Player died!\");\n }\n\n [WButton(\"Add Gold\", groupName: \"Economy\")]\n private void AddGold()\n {\n gold += 100;\n Debug.Log($\"Gold: {gold}\");\n }\n\n [WButton(\"Roll Reward\", groupName: \"Economy\", historyCapacity: 10)]\n private int RollReward()\n {\n int amount = PRNG.Instance.Next(10, 100);\n gold += amount;\n return amount;\n }\n}\nusing UnityEngine;\nusing System.Threading;\nusing System.Threading.Tasks;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class DataManager : MonoBehaviour\n{\n [WButton(\"Load Player Data\")]\n private async Task<string> LoadPlayerDataAsync(CancellationToken ct)\n {\n Debug.Log(\"Loading player data...\");\n\n // Simulate network request\n await Task.Delay(2000, ct);\n\n string playerName = \"TestPlayer_\" + Random.Range(1000, 9999);\n Debug.Log($\"Loaded: {playerName}\");\n\n return playerName;\n }\n\n [WButton(\"Batch Load\", historyCapacity: 5)]\n private async Task<int> BatchLoadAsync(CancellationToken ct)\n {\n int count = 0;\n for (int i = 0; i < 10; i++)\n {\n ct.ThrowIfCancellationRequested();\n await Task.Delay(200, ct);\n count++;\n Debug.Log($\"Loaded item {count}/10\");\n }\n return count;\n }\n}\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class LevelGenerator : MonoBehaviour\n{\n [WButton(\"Generate Seed\", historyCapacity: 20)]\n private int GenerateSeed()\n {\n return Random.Range(1000, 9999);\n }\n\n [WButton(\"Generate Level\")]\n private void GenerateLevel()\n {\n int seed = Random.Range(1000, 9999);\n Random.InitState(seed);\n Debug.Log($\"Generating level with seed: {seed}\");\n // ... generation logic ...\n }\n\n [WButton(\"Clear Level\", colorKey: \"Default-Dark\")]\n private void ClearLevel()\n {\n // ... cleanup logic ...\n Debug.Log(\"Level cleared\");\n }\n\n [WButton(\"Generate with Seed\")]\n private void GenerateWithSeed(int seed)\n {\n Random.InitState(seed);\n Debug.Log($\"Generating with seed: {seed}\");\n // ... generation logic ...\n }\n}\nusing System.Collections;\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class AnimationTester : MonoBehaviour\n{\n public SpriteRenderer spriteRenderer;\n\n private void Awake()\n {\n spriteRenderer = GetComponent<SpriteRenderer>();\n }\n\n [WButton(\"Fade Out\", groupName: \"Animations\")]\n private IEnumerator FadeOutCoroutine()\n {\n Color color = spriteRenderer.color;\n while (color.a > 0f)\n {\n color.a -= Time.deltaTime;\n spriteRenderer.color = color;\n yield return null;\n }\n Debug.Log(\"Fade out complete\");\n }\n\n [WButton(\"Fade In\", groupName: \"Animations\")]\n private IEnumerator FadeInCoroutine()\n {\n Color color = spriteRenderer.color;\n while (color.a < 1f)\n {\n color.a += Time.deltaTime;\n spriteRenderer.color = color;\n yield return null;\n }\n Debug.Log(\"Fade in complete\");\n }\n\n [WButton(\"Pulse\", groupName: \"Animations\")]\n private IEnumerator PulseCoroutine()\n {\n Vector3 originalScale = transform.localScale;\n for (int i = 0; i < 3; i++)\n {\n transform.localScale = originalScale * 1.2f;\n yield return new WaitForSeconds(0.2f);\n transform.localScale = originalScale;\n yield return new WaitForSeconds(0.2f);\n }\n Debug.Log(\"Pulse complete\");\n }\n}\nWButton works automatically with:
MonoBehaviour, ScriptableObject, etc.)SerializedMonoBehaviour and SerializedScriptableObject (when ODIN_INSPECTOR is defined)When do you need WButtonEditorHelper?
Only when you create custom Odin editors that override the default behavior. For example, if you create a CustomEditor that inherits from OdinEditor for a specific type, you'll need to integrate WButton manually.
No setup required! WButton automatically works with Odin's base types:
C##if ODIN_INSPECTOR\nusing Sirenix.OdinInspector;\n#endif\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\n#if ODIN_INSPECTOR\npublic class MyComponent : SerializedMonoBehaviour\n#else\npublic class MyComponent : MonoBehaviour\n#endif\n{\n [WButton(\"Test Button\")]\n private void TestMethod()\n {\n Debug.Log(\"Button clicked!\");\n }\n}\nWButton will appear automatically in the inspector - no additional code needed!
"},{"location":"features/inspector/inspector-button/#integration-with-custom-odin-editors","title":"Integration with Custom Odin Editors","text":"If you create a custom Odin editor for your type, you need to manually integrate WButton using WButtonEditorHelper:
#if UNITY_EDITOR && ODIN_INSPECTOR\nusing Sirenix.OdinInspector.Editor;\nusing UnityEditor;\nusing WallstopStudios.UnityHelpers.Editor.Utils.WButton;\n\n// Custom editor for a specific type\n[CustomEditor(typeof(MyComponent))]\npublic class MyComponentEditor : OdinEditor\n{\n private WButtonEditorHelper _wButtonHelper;\n\n protected override void OnEnable()\n {\n base.OnEnable();\n _wButtonHelper = new WButtonEditorHelper();\n }\n\n public override void OnInspectorGUI()\n {\n // Draw WButtons at top (optional - based on your settings)\n _wButtonHelper.DrawButtonsAtTop(this);\n\n // Draw Odin inspector\n base.OnInspectorGUI();\n\n // Draw WButtons at bottom and process any invocations\n _wButtonHelper.DrawButtonsAtBottomAndProcessInvocations(this);\n }\n}\n#endif\nFor standard Unity custom editors:
C##if UNITY_EDITOR\nusing UnityEditor;\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Editor.Utils.WButton;\n\n[CustomEditor(typeof(MyComponent))]\npublic class MyComponentEditor : Editor\n{\n private WButtonEditorHelper _wButtonHelper;\n\n private void OnEnable()\n {\n _wButtonHelper = new WButtonEditorHelper();\n }\n\n public override void OnInspectorGUI()\n {\n serializedObject.Update();\n\n // Draw WButtons at top\n _wButtonHelper.DrawButtonsAtTop(this);\n\n // Draw your custom inspector\n DrawDefaultInspector();\n\n serializedObject.ApplyModifiedProperties();\n\n // Draw WButtons at bottom and process invocations\n _wButtonHelper.DrawButtonsAtBottomAndProcessInvocations(this);\n }\n}\n#endif\nThe WButtonEditorHelper class provides several methods for different use cases:
DrawButtonsAtTop(Editor) Draws buttons configured for top placement DrawButtonsAtBottom(Editor) Draws buttons configured for bottom placement ProcessInvocations() Processes any triggered button invocations DrawButtonsAtBottomAndProcessInvocations(Editor) Convenience method combining bottom drawing + processing (most common) DrawAllButtonsAndProcessInvocations(Editor) Draws all buttons in one location regardless of placement settings Key Points:
WButtonEditorHelper instance per editor (typically in OnEnable)DrawButtonsAtTop before your inspector contentDrawButtonsAtBottomAndProcessInvocations after your inspector contentProcessInvocations() after all button drawing is completeIf you prefer all buttons in one location regardless of placement settings:
C#public override void OnInspectorGUI()\n{\n // Your inspector code here\n DrawDefaultInspector();\n\n // Draw all buttons at the end\n _wButtonHelper.DrawAllButtonsAndProcessInvocations(this);\n}\nProblem: Method has [WButton] but button doesn't show
Solutions:
private or protected (public methods may conflict)Problem: Method returns a value but no history appears
Solutions:
historyCapacity - make sure it's > 0UnityHelpersSettings.WButtonHistorySize if using global settingProblem: Cancel button doesn't stop an async method
Solutions:
CancellationToken parameterct.ThrowIfCancellationRequested()await Task.Delay(1000, ct)// \u2705 CORRECT: Cancellable\n[WButton(\"Long Task\")]\nprivate async Task LongTaskAsync(CancellationToken ct)\n{\n for (int i = 0; i < 100; i++)\n {\n ct.ThrowIfCancellationRequested(); // Check token\n await Task.Delay(100, ct); // Pass token\n }\n}\nNext Steps:
groupName to organize buttonsCancellationToken supportUnityHelpersSettings.assetShow or hide fields dynamically based on runtime values.
The [WShowIf] attribute creates dynamic inspector layouts that adapt to field values without writing custom PropertyDrawers. Perfect for reducing clutter, creating a contextual UI, and guiding designers toward valid configurations.
using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class WeaponConfig : MonoBehaviour\n{\n public bool isRanged;\n\n [WShowIf(nameof(isRanged))]\n public float projectileSpeed = 10f; // Only visible when isRanged == true\n\n [WShowIf(nameof(isRanged), inverse: true)]\n public float meleeRange = 2f; // Only visible when isRanged == false\n}\n[WShowIf(\n string conditionField, // Required: Field/property name to evaluate\n WShowIfComparison comparison = Equal, // Comparison operator\n bool inverse = false, // Invert the result\n params object[] expectedValues // Expected values for equality checks\n)]\npublic enum WShowIfComparison\n{\n Equal, // ==\n NotEqual, // !=\n GreaterThan, // >\n GreaterThanOrEqual, // >=\n LessThan, // <\n LessThanOrEqual, // <=\n IsNull, // == null\n IsNotNull, // != null\n IsNullOrEmpty, // string.IsNullOrEmpty or collection.Count == 0\n IsNotNullOrEmpty // !string.IsNullOrEmpty and collection.Count > 0\n}\npublic enum WeaponType { Melee, Ranged, Magic }\n\npublic WeaponType weaponType;\n\n[WShowIf(nameof(weaponType), WShowIfComparison.Equal, WeaponType.Ranged)]\npublic int ammoCapacity = 30;\n\n[WShowIf(nameof(weaponType), WShowIfComparison.NotEqual, WeaponType.Melee)]\npublic float castTime = 1f; // Visible for Ranged or Magic\npublic class Ability : ScriptableObject { }\n\n[Range(0, 100)]\npublic int playerLevel = 1;\n\n[WShowIf(nameof(playerLevel), WShowIfComparison.GreaterThan, 5)]\npublic Ability specialAbility;\n\n[WShowIf(nameof(playerLevel), WShowIfComparison.GreaterThanOrEqual, 10)]\npublic Ability ultimateAbility;\n\n[WShowIf(nameof(playerLevel), WShowIfComparison.LessThan, 5)]\npublic string tutorialMessage = \"Level up to unlock abilities\";\npublic GameObject targetPrefab;\n\n[WShowIf(nameof(targetPrefab), WShowIfComparison.IsNotNull)]\npublic int spawnCount = 1;\n\n[WShowIf(nameof(targetPrefab), WShowIfComparison.IsNull)]\npublic string warningMessage = \"Assign a prefab to spawn!\";\npublic List<GameObject> enemies;\n\n[WShowIf(nameof(enemies), WShowIfComparison.IsNotNullOrEmpty)]\npublic float spawnInterval = 2f;\n\n[WShowIf(nameof(enemies), WShowIfComparison.IsNullOrEmpty)]\npublic string hint = \"Add enemies to the list\";\npublic bool enableFeature;\n\n[WShowIf(nameof(enableFeature))]\npublic float featurePower = 1.0f;\npublic float health = 100f;\n\n[WShowIf(nameof(health), WShowIfComparison.LessThanOrEqual, 30f)]\npublic Color lowHealthColor = Color.red;\npublic enum Difficulty { Easy, Normal, Hard }\n\npublic Difficulty difficulty;\n\n[WShowIf(nameof(difficulty), WShowIfComparison.Equal, Difficulty.Hard)]\npublic float hardModeMultiplier = 2.5f;\npublic string playerName;\n\n[WShowIf(nameof(playerName), WShowIfComparison.IsNotNullOrEmpty)]\npublic Sprite playerAvatar;\n\n[WShowIf(nameof(playerName), WShowIfComparison.Equal, \"admin\")]\npublic bool debugMode;\npublic AudioSource audioSource;\n\n[WShowIf(nameof(audioSource), WShowIfComparison.IsNotNull)]\npublic AudioClip soundEffect;\npublic GameObject[] spawnPoints;\n\n[WShowIf(nameof(spawnPoints), WShowIfComparison.IsNotNullOrEmpty)]\npublic GameObject enemyPrefab;\npublic bool useCustomColor;\n\n// Show when useCustomColor == false\n[WShowIf(nameof(useCustomColor), inverse: true)]\npublic string colorPreset = \"Default\";\n\n// Show when useCustomColor == true\n[WShowIf(nameof(useCustomColor))]\npublic Color customColor = Color.white;\npublic enum GameState { MainMenu, Playing, Paused, GameOver }\n\npublic GameState state;\n\n// Show when state is Playing OR Paused\n[WShowIf(nameof(state), WShowIfComparison.Equal, GameState.Playing, GameState.Paused)]\npublic float gameTimer;\n\n// Show when state is MainMenu OR GameOver\n[WShowIf(nameof(state), WShowIfComparison.Equal, GameState.MainMenu, GameState.GameOver)]\npublic string menuText;\npublic bool isEnabled;\npublic int level;\n\n// Both conditions must be true (AND logic)\n[WShowIf(nameof(isEnabled))]\n[WShowIf(nameof(level), WShowIfComparison.GreaterThan, 5)]\npublic Ability advancedFeature;\nNote: Multiple [WShowIf] attributes create AND logic (all must be true).
public class Enemy : MonoBehaviour\n{\n public float health = 100f;\n\n // Property (computed)\n public bool IsAlive => health > 0f;\n\n // Show when IsAlive == true\n [WShowIf(nameof(IsAlive))]\n public float damageResistance = 0.5f;\n\n // Method (no parameters)\n public bool ShouldShowDebug() => Application.isEditor && Debug.isDebugBuild;\n\n [WShowIf(nameof(ShouldShowDebug))]\n public string debugInfo;\n}\nSupported:
// \u2705 GOOD: Fields only relevant in specific contexts\npublic enum AbilityType { Passive, Active, Toggle }\n\npublic AbilityType abilityType;\n\n[WShowIf(nameof(abilityType), WShowIfComparison.Equal, AbilityType.Active)]\npublic float cooldown = 5f;\n\n[WShowIf(nameof(abilityType), WShowIfComparison.Equal, AbilityType.Toggle)]\npublic float energyDrainPerSecond = 10f;\n\n// \u274c BAD: Hiding core settings\n[WShowIf(nameof(advancedMode))]\npublic float maxHealth = 100f; // Always needed, shouldn't hide!\n// \u2705 GOOD: Show hint when condition is false\npublic GameObject weaponPrefab;\n\n[WShowIf(nameof(weaponPrefab), WShowIfComparison.IsNull)]\npublic string hint = \"\u26a0\ufe0f Assign a weapon prefab above\";\n\n[WShowIf(nameof(weaponPrefab), WShowIfComparison.IsNotNull)]\npublic int weaponDamage = 10;\n\n// \u274c BAD: No indication why fields are missing\n[WShowIf(nameof(weaponPrefab), WShowIfComparison.IsNotNull)]\npublic int weaponDamage = 10; // User may not realize they need to assign prefab\n// \u2705 GOOD: Flat conditions\npublic bool featureA;\npublic bool featureB;\n\n[WShowIf(nameof(featureA))]\npublic float settingA;\n\n[WShowIf(nameof(featureB))]\npublic float settingB;\n\n// \u274c BAD: Overly complex dependencies\npublic bool enableAdvanced;\npublic bool enableExperimental;\npublic bool enableDangerous;\n\n[WShowIf(nameof(enableAdvanced))]\n[WShowIf(nameof(enableExperimental))]\n[WShowIf(nameof(enableDangerous))]\npublic float obscureSetting; // Too many hoops to jump through!\n// \u2705 GOOD: Clean enum-based visibility\npublic enum InputMode { Keyboard, Gamepad, Touch }\n\npublic InputMode inputMode;\n\n[WShowIf(nameof(inputMode), WShowIfComparison.Equal, InputMode.Keyboard)]\npublic KeyCode actionKey = KeyCode.Space;\n\n[WShowIf(nameof(inputMode), WShowIfComparison.Equal, InputMode.Gamepad)]\npublic string gamepadButton = \"A\";\n\n[WShowIf(nameof(inputMode), WShowIfComparison.Equal, InputMode.Touch)]\npublic Vector2 touchRegion = new Vector2(100, 100);\n\n// \u274c BAD: Boolean spaghetti\npublic bool useKeyboard;\npublic bool useGamepad;\n\n[WShowIf(nameof(useKeyboard))]\npublic KeyCode actionKey; // What if both are true?\n\n[WShowIf(nameof(useGamepad))]\npublic string gamepadButton;\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class Weapon : MonoBehaviour\n{\n public enum WeaponType { Melee, Ranged, Magic }\n\n public WeaponType weaponType;\n\n [WShowIf(nameof(weaponType), WShowIfComparison.Equal, WeaponType.Melee)]\n public float meleeRange = 2f;\n\n [WShowIf(nameof(weaponType), WShowIfComparison.Equal, WeaponType.Melee)]\n public float swingSpeed = 1f;\n\n [WShowIf(nameof(weaponType), WShowIfComparison.Equal, WeaponType.Ranged)]\n public GameObject projectilePrefab;\n\n [WShowIf(nameof(weaponType), WShowIfComparison.Equal, WeaponType.Ranged)]\n public int maxAmmo = 30;\n\n [WShowIf(nameof(weaponType), WShowIfComparison.Equal, WeaponType.Magic)]\n public float manaCost = 15f;\n\n [WShowIf(nameof(weaponType), WShowIfComparison.Equal, WeaponType.Magic)]\n public ParticleSystem spellEffect;\n}\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class AIController : MonoBehaviour\n{\n public bool enableAI = true;\n\n [WShowIf(nameof(enableAI), inverse: true)]\n public string disabledMessage = \"AI is disabled\";\n\n [WShowIf(nameof(enableAI))]\n public float detectionRange = 10f;\n\n [WShowIf(nameof(enableAI))]\n public float attackRange = 2f;\n\n [WShowIf(nameof(enableAI))]\n public bool canFlee = true;\n\n [WShowIf(nameof(canFlee))]\n [WShowIf(nameof(enableAI))]\n public float fleeHealthThreshold = 0.3f;\n}\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class PlayerProgression : MonoBehaviour\n{\n public int level = 1;\n\n [WShowIf(nameof(level), WShowIfComparison.LessThan, 5)]\n public string beginnerTip = \"Complete quests to level up\";\n\n [WShowIf(nameof(level), WShowIfComparison.GreaterThanOrEqual, 5)]\n public Ability specialAbility;\n\n [WShowIf(nameof(level), WShowIfComparison.GreaterThanOrEqual, 10)]\n public Ability advancedAbility;\n\n [WShowIf(nameof(level), WShowIfComparison.GreaterThanOrEqual, 20)]\n public Ability ultimateAbility;\n\n [WShowIf(nameof(level), WShowIfComparison.GreaterThanOrEqual, 20)]\n public GameObject legendaryWeapon;\n}\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class MultiplayerConfig : MonoBehaviour\n{\n public bool isHost = false;\n\n [WShowIf(nameof(isHost))]\n public int maxPlayers = 4;\n\n [WShowIf(nameof(isHost))]\n public string serverPassword;\n\n [WShowIf(nameof(isHost), inverse: true)]\n public string serverAddress = \"localhost\";\n\n [WShowIf(nameof(isHost), inverse: true)]\n public int serverPort = 7777;\n}\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class GraphicsSettings : MonoBehaviour\n{\n public enum QualityLevel { Low, Medium, High, Ultra }\n\n public QualityLevel quality = QualityLevel.Medium;\n\n [WShowIf(nameof(quality), WShowIfComparison.GreaterThanOrEqual, QualityLevel.Medium)]\n public bool enableShadows = true;\n\n [WShowIf(nameof(quality), WShowIfComparison.GreaterThanOrEqual, QualityLevel.High)]\n public bool enableReflections = true;\n\n [WShowIf(nameof(quality), WShowIfComparison.Equal, QualityLevel.Ultra)]\n public bool enableRayTracing = false;\n\n [WShowIf(nameof(quality), WShowIfComparison.Equal, QualityLevel.Ultra)]\n public int antiAliasingLevel = 8;\n}\nProblem: Field doesn't appear when a condition should be true
Solutions:
conditionField parameterpublic (private fields not supported)inverse: true to see if logic is invertedWShowIfComparison.Equal explicitly instead of relying on defaultProblem: Error: \"Could not find field/property 'X'\"
Solutions:
public (not private or protected)Problem: Stacking [WShowIf] doesn't work as expected
Current Behavior: Multiple attributes create AND logic (all must be true)
Workaround for OR logic: Use a helper property
C#public bool condition1;\npublic bool condition2;\n\npublic bool EitherCondition => condition1 || condition2;\n\n[WShowIf(nameof(EitherCondition))]\npublic float myField;\nNext Steps:
[WGroup] for organized, dynamic layoutsOrganize your inspector without writing custom editors.
Unity Helpers provides powerful grouping attributes that create boxed sections and collapsible foldouts with zero boilerplate. These attributes rival commercial tools like Odin Inspector while offering unique features like auto-inclusion.
"},{"location":"features/inspector/inspector-grouping-attributes/#table-of-contents","title":"Table of Contents","text":"Creates boxed inspector sections with optional collapsible headers and automatic field inclusion.
\u26a0\ufe0f Important: [WGroupEnd] must be placed on the last field you want included in the group. The field with [WGroupEnd] IS included in the group, and then the group closes for subsequent fields.
using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class CharacterStatsWGroup : MonoBehaviour\n{\n // Simple box with 4 fields\n [WGroup(\"combat\", \"Combat Stats\")]\n public float maxHealth = 100f;\n public float defense = 10f;\n public float attackPower = 25f;\n [WGroupEnd(\"combat\")] // criticalChance IS included, then group closes\n public float criticalChance = 0.15f;\n\n public string characterName; // Not in group (comes after WGroupEnd)\n}\n[WGroup(\n string groupName, // Required: Unique identifier\n string displayName = null, // Optional: Header text (defaults to groupName)\n int autoIncludeCount = UseGlobalAutoInclude, // Auto-include N fields (or use global setting)\n bool collapsible = false, // Enable foldout behavior\n bool startCollapsed = false, // Initial collapsed state\n bool hideHeader = false, // Draw body without header bar\n string parentGroup = null // Optional: Nest inside another group\n)]\n\ud83d\udca1 Use the optional CollapseBehavior named argument (or startCollapsed: true) to override the project-wide default configured under Project Settings \u25b8 Wallstop Studios \u25b8 Unity Helpers \u25b8 Start WGroups Collapsed. Example:
[WGroup(\n \"advanced\",\n collapsible: true,\n CollapseBehavior = WGroupAttribute.WGroupCollapseBehavior.ForceExpanded\n)]\nCollapseBehavior options:
UseProjectSetting (default) \u2013 defers to the Unity Helpers project setting.ForceExpanded \u2013 always starts expanded.ForceCollapsed \u2013 always starts collapsed (equivalent to startCollapsed: true).[WGroup(\"items\", \"Inventory\", autoIncludeCount: 3)]\npublic GameObject weapon; // Field 1: in group\npublic GameObject armor; // Field 2: in group (auto-included)\n[WGroupEnd(\"items\")] // accessory IS included (field 3), then group closes\npublic GameObject accessory; // Field 3: in group (last field)\n\npublic int gold; // NOT in group (comes after WGroupEnd)\n[WGroup(\"settings\", \"Settings\", autoIncludeCount: WGroupAttribute.InfiniteAutoInclude)]\npublic bool enableSound; // In group\npublic bool enableMusic; // In group (auto-included)\npublic float volume; // In group (auto-included)\n// ... 20 more fields ... // All auto-included\n[WGroupEnd(\"settings\")] // lastField IS included, then group closes\npublic bool lastField; // In group (last field)\n\npublic int outsideGroup; // NOT in group (comes after WGroupEnd)\n// Uses WGroupAutoIncludeRowCount from ProjectSettings/UnityHelpersSettings.asset (default: 4)\n[WGroup(\"stats\", \"Stats\")] // autoIncludeCount defaults to UseGlobalAutoInclude\npublic int strength; // Field 1: in group\npublic int intelligence; // Field 2: in group (auto-included)\npublic int agility; // Field 3: in group (auto-included)\n[WGroupEnd(\"stats\")] // luck IS included (field 4), then group closes\npublic int luck; // Field 4: in group (last field)\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class WGroupEndExample : MonoBehaviour\n{\n [WGroup(\"advanced\", \"Advanced Options\", collapsible: true, startCollapsed: true)]\n public float raycastDistance = 100f; // In group\n public LayerMask collisionMask; // In group (auto-included)\n\n [WGroupEnd(\"advanced\")] // debugDraw IS included, then group closes\n public bool debugDraw; // In group (last field)\n\n public bool someOtherField; // NOT in group (comes after WGroupEnd)\n}\nAnimation Settings:
UnityHelpersSettings.WGroupFoldoutSpeed (default: 2.0, range: 2.0-12.0)UnityHelpersSettings.WGroupFoldoutTweenEnabled (default: enabled)Configure in Project Settings \u2192 Unity Helpers or see Inspector Settings for details.
"},{"location":"features/inspector/inspector-grouping-attributes/#hiding-headers","title":"Hiding Headers","text":"C#using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class HealthExample : MonoBehaviour\n{\n [WGroup(\"stealth\", \"\", hideHeader: true)]\n public float opacity = 1f; // In group\n\n [WGroupEnd(\"stealth\")] // isVisible IS included, then group closes\n public bool isVisible = true; // In group (last field)\n}\nUse Cases:
Use the parentGroup parameter to nest one group inside another. Nested groups render visually inside their parent's box, with accumulated indentation and padding.
using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class NestedGroupExample : MonoBehaviour\n{\n [WGroup(\"outer\", \"Character\")]\n public string characterName; // In outer group\n\n [WGroup(\"inner\", \"Stats\", parentGroup: \"outer\")]\n public int level; // In inner group (nested in outer)\n public int experience; // In inner group (auto-included)\n\n [WGroupEnd(\"inner\")] // faction IS included in BOTH groups\n [WGroupEnd(\"outer\")] // Then both groups close\n public string faction; // In inner AND outer groups (last field)\n}\nHow Nesting Works:
[WGroup(\"outer\", ...)]parentGroup: \"outer\" parameterMultiple Nesting Levels:
C#[WGroup(\"level1\", \"Level 1\")]\npublic string field1; // In level1 only\n\n[WGroup(\"level2\", \"Level 2\", parentGroup: \"level1\")]\npublic string field2; // In level2 (nested in level1)\n\n[WGroup(\"level3\", \"Level 3\", parentGroup: \"level2\")]\npublic string field3; // In level3 (nested in level2 \u2192 level1)\n[WGroupEnd(\"level3\")] // field4 IS included in all three groups\n[WGroupEnd(\"level2\")] // Then all groups close in order\n[WGroupEnd(\"level1\")]\npublic string field4; // In level3, level2, AND level1 (last field)\nSibling Nested Groups:
C#[WGroup(\"parent\", \"Parent\")]\npublic string parentField; // In parent group\n\n[WGroup(\"child1\", \"Child 1\", parentGroup: \"parent\")]\npublic string child1Field; // In child1 (nested in parent)\n\n[WGroupEnd(\"child1\")] // child2Field starts NEW group, so closes child1 first\n[WGroup(\"child2\", \"Child 2\", parentGroup: \"parent\")]\npublic string child2Field; // In child2 (nested in parent)\n\n[WGroupEnd(\"child2\")] // afterParent IS included in child2 AND parent\n[WGroupEnd(\"parent\")] // Then both groups close\npublic string afterParent; // In child2 AND parent groups (last field)\nImportant Notes:
parentGroup references a non-existent group, the child is rendered as a top-level group\u26a0\ufe0f Key Point: [WGroupEnd] must always be attached to a field. The field with [WGroupEnd] IS included in the group (via auto-include), and then the group closes.
[WGroup(\"combat\", \"Combat Stats\")]\npublic int health; // In group\npublic int defense; // In group (auto-included)\n[WGroupEnd(\"combat\")] // stamina IS included, then \"combat\" closes\npublic int stamina; // In group (last field)\n\npublic int unrelatedField; // NOT in group\nWhen closing nested groups, stack multiple [WGroupEnd] attributes on the last field:
[WGroup(\"outer\", \"Outer\")]\npublic int outerField; // In outer\n\n[WGroup(\"inner\", \"Inner\", parentGroup: \"outer\")]\npublic int innerField; // In inner (nested in outer)\n\n[WGroupEnd(\"inner\")] // lastField IS included in both groups\n[WGroupEnd(\"outer\")] // Then both groups close\npublic int lastField; // In inner AND outer (last field)\nOmit the group name to close all currently active auto-include groups:
C#[WGroup(\"settings\", autoIncludeCount: WGroupAttribute.InfiniteAutoInclude)]\npublic bool enableSound; // In group\npublic float volume; // In group (auto-included)\n[WGroupEnd] // lastSetting IS included, then ALL groups close\npublic bool lastSetting; // In group (last field)\n\npublic int outsideAllGroups; // NOT in any group\npublic class WGroupAttribute\n{\n public const int InfiniteAutoInclude = -1; // Include until WGroupEnd\n public const int UseGlobalAutoInclude = -2; // Default: use project setting\n}\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class WGroupOutOfOrderExample : MonoBehaviour\n{\n [WGroup(\"settings\", \"Game Settings\", autoIncludeCount: 1)]\n public float masterVolume;\n public float musicVolume;\n\n public int numChannels;\n\n // Later in the same script...\n [WGroup(\"settings\", autoIncludeCount: 1)] // Reuses \"Game Settings\" header, included in original group\n public float sfxVolume;\n\n [WGroupEnd(\"settings\")]\n public bool enableSound;\n}\nNote: Multiple [WGroup] attributes with the same groupName merge into a single group instance. This allows for logical grouping of related fields that may not be contiguous in code.
All grouping attributes respect project-wide settings defined in UnityHelpersSettings:
Location: ProjectSettings/UnityHelpersSettings.asset
Settings:
WGroupAutoIncludeRowCount (default: 4) - Default fields to auto-includeWGroupStartCollapsed (default: true) - Whether collapsible groups start collapsedWGroupFoldoutTweenEnabled (default: true) - Enable expand/collapse animationsWGroupFoldoutSpeed (default: 2.0, range: 2-12) - Animation speed// \u2705 GOOD: Clear, descriptive group names\n[WGroup(\"combat\", \"Combat Stats\")]\n[WGroup(\"movement\", \"Movement Settings\")]\n[WGroup(\"visuals\", \"Visual Effects\")]\n\n// \u274c BAD: Vague or inconsistent\n[WGroup(\"group1\", \"Stuff\")]\n[WGroup(\"misc\", \"Things\")]\n// \u2705 GOOD: Explicit count for small groups\n[WGroup(\"position\", \"Position\", autoIncludeCount: 3)]\npublic Vector3 position; // Field 1: in group\npublic Quaternion rotation; // Field 2: in group (auto-included)\n[WGroupEnd(\"position\")] // scale IS included (field 3), then group closes\npublic Vector3 scale; // Field 3: in group (last field)\n\n// \u2705 GOOD: Infinite for dynamic/long lists\n[WGroup(\"inventory\", \"Items\", autoIncludeCount: WGroupAttribute.InfiniteAutoInclude)]\npublic List<GameObject> weapons; // In group\npublic List<GameObject> consumables; // In group (auto-included)\n// ... many more fields ... // All auto-included\n[WGroupEnd(\"inventory\")] // lastItem IS included, then group closes\npublic int lastItem; // In group (last field)\n\n// \u274c BAD: Infinite without WGroupEnd (includes everything below!)\n[WGroup(\"bad\", autoIncludeCount: WGroupAttribute.InfiniteAutoInclude)]\npublic int field1;\npublic int field2;\n// Oops, forgot [WGroupEnd]!\npublic string unrelatedField; // Also included!\n// \u2705 GOOD: Always-visible for frequently accessed data\n[WGroup(\"core\", \"Core Stats\", collapsible: false)]\npublic float health; // In group\n[WGroupEnd(\"core\")] // energy IS included, then group closes\npublic float energy; // In group (last field)\n\n// \u2705 GOOD: Collapsible for optional/advanced features\n[WGroup(\"advanced\", \"Advanced\", collapsible: true, startCollapsed: true)]\npublic float debugParameter; // In group\n[WGroupEnd(\"advanced\")] // experimentalFeature IS included, then closes\npublic bool experimentalFeature; // In group (last field)\n\n// \u274c BAD: Everything collapsible (hides important data)\n[WGroup(\"important\", \"Critical Settings\", collapsible: true, startCollapsed: true, autoIncludeCount: 0)]\npublic float maxHealth; // Why hide this?\nusing System.Collections.Generic;\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class RPGCharacter : MonoBehaviour\n{\n [WGroup(\"identity\", \"Identity\")]\n public string characterName; // In identity group\n public Sprite portrait; // In identity group (auto-included)\n public string className; // In identity group (auto-included)\n\n [WGroupEnd(\"identity\")] // strength IS included, then identity closes\n [WGroup(\"attributes\", \"Base Attributes\", collapsible: true)]\n public int strength = 10; // In identity (last) AND starts attributes\n public int agility = 10; // In attributes (auto-included)\n public int intelligence = 10; // In attributes (auto-included)\n public int vitality = 10; // In attributes (auto-included)\n\n [WGroupEnd(\"attributes\")] // maxHealth IS included, then attributes closes\n [WGroup(\"combat\", \"Combat Stats\")]\n public float maxHealth = 100f; // In attributes (last) AND starts combat\n public float attackPower = 25f; // In combat (auto-included)\n public float defense = 15f; // In combat (auto-included)\n\n [WGroupEnd(\"combat\")] // learnedSkills IS included, then combat closes\n [WGroup(\"skills\", \"Skills\", collapsible: true, startCollapsed: true)]\n public List<string> learnedSkills = new(); // In combat (last) AND starts skills\n\n [WGroupEnd(\"skills\")] // skillPoints IS included, then skills closes\n public int skillPoints = 0; // In skills (last field)\n}\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic enum DamageType\n{\n Physical,\n Magic,\n}\n\npublic class WeaponConfig2 : MonoBehaviour\n{\n [WGroup(\"basic\", \"Basic Info\", autoIncludeCount: 2)]\n public string weaponName; // Field 1: in basic group\n\n [WGroupEnd(\"basic\")] // icon IS included (field 2), then closes\n public Sprite icon; // Field 2: in basic (last field)\n\n [WGroup(\"damage\", \"Damage\", collapsible: true)]\n public float baseDamage = 10f; // In damage group\n public float criticalMultiplier = 2f; // In damage (auto-included)\n\n [WGroupEnd(\"damage\")] // damageType IS included, then closes\n public DamageType damageType; // In damage (last field)\n\n [WGroup(\"effects\", \"Special Effects\", collapsible: true, startCollapsed: true)]\n public ParticleSystem hitEffect; // In effects group\n public AudioClip hitSound; // In effects (auto-included)\n\n [WGroupEnd(\"effects\")] // effectDuration IS included, then closes\n public float effectDuration = 1f; // In effects (last field)\n\n [WGroup(\"advanced\", \"Advanced Settings\", collapsible: true, startCollapsed: true)]\n public float projectileSpeed = 20f; // In advanced group\n public LayerMask targetLayers; // In advanced (auto-included)\n\n [WGroupEnd(\"advanced\")] // debugMode IS included, then closes\n public bool debugMode = false; // In advanced (last field)\n}\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class LevelSettings : MonoBehaviour\n{\n [WGroup(\"general\", \"General\", autoIncludeCount: 3)]\n public string levelName; // Field 1: in general group\n public Sprite thumbnail; // Field 2: in general (auto-included)\n\n [WGroupEnd(\"general\")] // description IS included (field 3), then closes\n public string description; // Field 3: in general (last field)\n\n [WGroup(\n \"environment\",\n \"Environment\",\n collapsible: true,\n startCollapsed: true,\n autoIncludeCount: WGroupAttribute.InfiniteAutoInclude\n )]\n public Color skyColor; // In environment group\n public Color fogColor; // In environment (auto-included)\n public float fogDensity; // In environment (auto-included)\n public Light directionalLight; // In environment (auto-included)\n public Cubemap skybox; // In environment (auto-included)\n public float ambientIntensity; // In environment (auto-included)\n\n [WGroupEnd(\"environment\")] // sunIntensity IS included, then closes\n public float sunIntensity; // In environment (last field)\n\n [WGroup(\"gameplay\", \"Gameplay Rules\", collapsible: true, startCollapsed: false)]\n public int enemyCount = 10; // In gameplay group\n public float difficultyMultiplier = 1f; // In gameplay (auto-included)\n\n [WGroupEnd(\"gameplay\")] // allowRespawns IS included, then closes\n public bool allowRespawns = true; // In gameplay (last field)\n\n [WGroup(\"debug\", \"Debug Options\", collapsible: true, startCollapsed: true)]\n public bool godMode = false; // In debug group\n public bool unlimitedAmmo = false; // In debug (auto-included)\n\n [WGroupEnd(\"debug\")] // showHitboxes IS included, then closes\n public bool showHitboxes = false; // In debug (last field)\n}\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class AIController : MonoBehaviour\n{\n [WGroup(\"outer\", \"AI Configuration\")]\n [WGroup(\"detection\", \"Detection\", parentGroup: \"outer\")]\n public float sightRange = 10f; // In detection (nested in outer)\n\n [WGroupEnd(\"detection\")] // hearingRange IS included, then detection closes\n public float hearingRange = 5f; // In detection (last) AND outer (auto-included)\n\n [WGroup(\"behavior\", \"Behavior\", parentGroup: \"outer\")]\n public float aggressionLevel = 0.5f; // In behavior (nested in outer)\n\n [WGroupEnd(\"behavior\")] // retreatThreshold IS included in both\n [WGroupEnd(\"outer\")] // Then both groups close\n public float retreatThreshold = 0.2f; // In behavior (last) AND outer (last)\n}\nProblem: Fields not showing in a group
Solutions:
autoIncludeCount - make sure it includes all desired fieldsWGroupEnd placement - the field WITH WGroupEnd IS included, fields AFTER are excludedWGroup and WGroupEnd// \u274c WRONG: Count too low (only 2 fields included, but intelligence has WGroupEnd)\n[WGroup(\"stats\", autoIncludeCount: 2)]\npublic int strength; // Field 1: in group\npublic int agility; // Field 2: in group (auto-included)\n[WGroupEnd(\"stats\")] // intelligence would be field 3, but count is only 2!\npublic int intelligence; // NOT included - auto-include budget exhausted before WGroupEnd\n\n\n// \u2705 CORRECT: Increase count to include the WGroupEnd field\n[WGroup(\"stats\", autoIncludeCount: 3)]\npublic int strength; // Field 1: in group\npublic int agility; // Field 2: in group (auto-included)\n[WGroupEnd(\"stats\")] // intelligence IS included (field 3), then group closes\npublic int intelligence; // Field 3: in group (last field)\nProblem: Groups don't animate when collapsed/expanded
Solutions:
UnityHelpersSettings.WGroupFoldoutTweenEnabled is truecollapsible: true is set for WGroupWGroupFoldoutSpeed isn't set too low (minimum is 2.0)WGroup operates at the inspector level, so existing property drawers and custom inspectors continue to work. Groups appear in the order of their first declaration, and multi-object editing remains fully supported.
"},{"location":"features/inspector/inspector-grouping-attributes/#see-also","title":"See Also","text":"Next Steps:
[WGroup][WButton] to add method buttons to your groupsEdit nested objects without losing context.
The [WInLineEditor] attribute embeds the inspector for object references (ScriptableObjects, Materials, Components, Textures, etc.) directly below the field. No more clicking through to edit configuration \u2014 everything stays in view.
using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class AbilityConfig : ScriptableObject\n{\n public string displayName;\n public float cooldown;\n public Sprite icon;\n}\n\npublic class Character : MonoBehaviour\n{\n [WInLineEditor]\n public AbilityConfig primaryAbility; // Editable inline!\n}\nVisual Reference
WInLineEditor with embedded inspector for a ScriptableObject reference
"},{"location":"features/inspector/inspector-inline-editor/#display-modes","title":"Display Modes","text":"Control how the inline editor appears using WInLineEditorMode:
AlwaysExpanded Always shows the inline inspector (no foldout) FoldoutExpanded Shows a foldout that starts expanded FoldoutCollapsed Shows a foldout that starts collapsed (default) C#using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class WInlineEditorModes : MonoBehaviour\n{\n // Always visible\n [WInLineEditor(WInLineEditorMode.AlwaysExpanded)]\n public AbilityConfig alwaysVisibleConfig;\n\n // Foldout, starts open\n [WInLineEditor(WInLineEditorMode.FoldoutExpanded)]\n public AbilityConfig expandedByDefault;\n\n // Foldout, starts closed (default behavior)\n [WInLineEditor(WInLineEditorMode.FoldoutCollapsed)]\n public AbilityConfig collapsedByDefault;\n\n // Uses global setting from Unity Helpers Settings\n [WInLineEditor]\n public AbilityConfig usesGlobalSetting;\n}\nVisual Reference
Comparison of AlwaysExpanded, FoldoutExpanded, and FoldoutCollapsed modes
"},{"location":"features/inspector/inspector-inline-editor/#configuration-options","title":"Configuration Options","text":"Fine-tune the presentation with constructor parameters:
C#[WInLineEditor(\n WInLineEditorMode.FoldoutCollapsed, // Display mode\n inspectorHeight: 200f, // Vertical space (min 160)\n drawObjectField: true, // Show object picker\n drawHeader: true, // Show bold header with ping button\n drawPreview: false, // Render preview area\n previewHeight: 64f, // Preview area height\n enableScrolling: true, // Wrap in scroll view\n minInspectorWidth: 520f // Horizontal scroll threshold (0 = disabled)\n)]\npublic AbilityConfig detailedConfig;\ninspectorHeight 200 Vertical space for inspector body (minimum 160) drawObjectField true Show the object picker field next to label drawHeader true Show bold header with ping button drawPreview false Render preview area (if target editor supports it) previewHeight 64 Height of preview area when enabled enableScrolling true Wrap inspector body in scroll view minInspectorWidth 520 Width threshold for horizontal scrollbar (0 = disabled)"},{"location":"features/inspector/inspector-inline-editor/#examples-with-options","title":"Examples with Options","text":"C#using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\nusing WallstopStudios.UnityHelpers.Utils;\n\npublic class AbilityDatabase : ScriptableObjectSingleton<AbilityDatabase>\n{\n // Compact: no header, no object field, fixed height\n [WInLineEditor(\n WInLineEditorMode.AlwaysExpanded,\n inspectorHeight: 180f,\n drawObjectField: false,\n drawHeader: false\n )]\n public AbilityConfig compactView;\n\n // Full featured: preview, scrolling, header with ping\n [WInLineEditor(\n WInLineEditorMode.FoldoutExpanded,\n inspectorHeight: 300f,\n drawPreview: true,\n previewHeight: 80f,\n enableScrolling: true\n )]\n public Sprite abilityIcon;\n}\nVisual Reference
Different configuration combinations showing compact vs full-featured layouts
"},{"location":"features/inspector/inspector-inline-editor/#animation-settings","title":"Animation Settings","text":"Foldout animations create smooth expand/collapse transitions. Configure globally via Edit > Project Settings > Unity Helpers:
Setting Default DescriptionInlineEditorFoldoutTweenEnabled true Enable/disable smooth animations InlineEditorFoldoutSpeed 2.0 Animation speed (2.0 - 12.0) C#using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class WInLineEditorAnimation : MonoBehaviour\n{\n // Animation applies to foldout modes only\n [WInLineEditor(WInLineEditorMode.FoldoutCollapsed)] // Animated\n public AbilityConfig animatedFoldout;\n\n [WInLineEditor(WInLineEditorMode.AlwaysExpanded)] // No animation\n public AbilityConfig noAnimation;\n}\nVisual Reference
Smooth expand/collapse animation with configurable speed
See also: Inspector Settings Reference for complete settings documentation.
"},{"location":"features/inspector/inspector-inline-editor/#supported-types","title":"Supported Types","text":"WInLineEditor works with any Unity Object reference:
public class VisualConfig : MonoBehaviour\n{\n [WInLineEditor]\n public Material sharedMaterial;\n\n [WInLineEditor(drawPreview: true, previewHeight: 128f)]\n public Texture2D backgroundTexture;\n\n [WInLineEditor]\n public AudioClip soundEffect;\n}\nHasPreviewGUI// Collapsed by default - keeps inspector clean\n[WInLineEditor(WInLineEditorMode.FoldoutCollapsed)]\npublic AdvancedSettings advancedSettings;\n\n// Always visible for frequently-edited config\n[WInLineEditor(WInLineEditorMode.AlwaysExpanded)]\npublic CoreSettings coreSettings;\n// Short config - minimal height\n[WInLineEditor(inspectorHeight: 160f)]\npublic SimpleConfig simple;\n\n// Complex config - more room\n[WInLineEditor(inspectorHeight: 400f, enableScrolling: true)]\npublic ComplexConfig complex;\n[WGroup(\"Visual Settings\")]\n[WInLineEditor]\npublic Material material; // In group\n\n[WInLineEditor]\n[WGroupEnd] // texture IS included, then group closes\npublic Texture2D texture; // In group (last field)\n\n[WGroup(\"Audio Settings\")]\n[WInLineEditor]\n[WGroupEnd] // clip IS included, then group closes\npublic AudioClip clip; // In group (last field)\n// When the reference shouldn't change, hide the picker\n[WInLineEditor(drawObjectField: false)]\npublic FixedConfiguration config;\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\n[CreateAssetMenu(menuName = \"Game/Ability Config\")]\npublic class AbilityConfig : ScriptableObject\n{\n public string displayName;\n public Sprite icon;\n public float cooldown = 1f;\n public float damage = 10f;\n public GameObject effectPrefab;\n}\n\npublic class CharacterAbilities : MonoBehaviour\n{\n [WGroup(\"Primary Abilities\")]\n [WInLineEditor(WInLineEditorMode.FoldoutExpanded)]\n public AbilityConfig primaryAttack; // In group\n\n [WInLineEditor(WInLineEditorMode.FoldoutCollapsed)]\n [WGroupEnd] // secondaryAttack IS included, then closes\n public AbilityConfig secondaryAttack; // In group (last field)\n\n [WGroup(\"Ultimate\")]\n [WInLineEditor(WInLineEditorMode.FoldoutCollapsed, inspectorHeight: 250f)]\n [WGroupEnd] // ultimate IS included, then closes\n public AbilityConfig ultimate; // In group (last field)\n}\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class VisualEffectController : MonoBehaviour\n{\n [WInLineEditor(\n WInLineEditorMode.FoldoutExpanded,\n inspectorHeight: 300f,\n drawPreview: true,\n previewHeight: 100f)]\n public Material effectMaterial;\n\n [WInLineEditor(drawPreview: true, previewHeight: 64f)]\n public Texture2D noiseTexture;\n}\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\n[CreateAssetMenu(menuName = \"Audio/Sound Config\")]\npublic class SoundConfig : ScriptableObject\n{\n public AudioClip clip;\n [Range(0f, 1f)] public float volume = 1f;\n [Range(0.5f, 2f)] public float pitch = 1f;\n public bool loop;\n}\n\npublic class AudioManager : MonoBehaviour\n{\n [WInLineEditor(WInLineEditorMode.FoldoutCollapsed)]\n public SoundConfig backgroundMusic;\n\n [WInLineEditor(WInLineEditorMode.FoldoutCollapsed)]\n public SoundConfig buttonClick;\n\n [WInLineEditor(WInLineEditorMode.FoldoutCollapsed)]\n public SoundConfig victorySound;\n}\nNext Steps:
[WInLineEditor] to ScriptableObject references for inline editing[WGroup] for organized inspector layoutsUnity Helpers includes a suite of inspector attributes and serialization types that change how you author components and data. These features eliminate repetitive code and provide designer-friendly workflows.
"},{"location":"features/inspector/inspector-overview/#why-use-these-features","title":"Why Use These Features?","text":"Time Savings:
[WGroup] attributeFeatures:
Control how fields are grouped and organized in the inspector:
using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class TwoWGroupExample : MonoBehaviour\n{\n [WGroup(\"Group 1\", collapsible: true)]\n public float health;\n public int intValue;\n public string stringValue;\n\n [WGroup(\"Group 2\", collapsible: true)]\n public float speed;\n public int otherIntValue;\n public string otherStringValue;\n}\n\u2192 Full Guide: Inspector Grouping Attributes
"},{"location":"features/inspector/inspector-overview/#2-inline-editing","title":"2. Inline Editing","text":"Edit nested objects without losing context:
using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\n[CreateAssetMenu(fileName = \"PowerUpDefinition\", menuName = \"Power-Up Definition\")]\npublic class PowerUpDefinition : ScriptableObject\n{\n public string powerUpName;\n public Sprite icon;\n}\n\npublic class WInLineEditorSimpleExample : MonoBehaviour\n{\n [WInLineEditor]\n public PowerUpDefinition powerUp;\n}\n
\u2192 Full Guide: Inspector Inline Editor
"},{"location":"features/inspector/inspector-overview/#3-method-invocation","title":"3. Method Invocation","text":"Expose methods as clickable buttons in the inspector:
using System;\nusing System.Collections;\nusing System.Threading;\nusing System.Threading.Tasks;\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\nusing WallstopStudios.UnityHelpers.Core.Extension;\n\npublic class WButtonOverviewExample : MonoBehaviour\n{\n [WButton]\n private void Test1()\n {\n this.Log($\"We did it!\");\n }\n\n [WButton]\n private IEnumerator KindaCoroutine()\n {\n this.Log($\"Starting coroutine...\");\n yield return new WaitForSeconds(1f);\n this.Log($\"Coroutine finished!\");\n }\n\n [WButton]\n private async Task AsyncWorksToo()\n {\n await Task.Delay(TimeSpan.FromSeconds(1));\n this.Log($\"Did it work?\");\n }\n\n [WButton]\n private async Task AsyncWorksTooWithCancellationTokens(CancellationToken ct)\n {\n await Task.Delay(TimeSpan.FromSeconds(1), ct);\n this.Log($\"Did it work?\");\n }\n\n [WButton]\n private async ValueTask ValueTasks(CancellationToken ct)\n {\n await Task.Delay(TimeSpan.FromSeconds(1), ct);\n this.Log($\"Did it work?\");\n }\n}\n
\u2192 Full Guide: Inspector Buttons
"},{"location":"features/inspector/inspector-overview/#4-conditional-display","title":"4. Conditional Display","text":"Show or hide fields based on runtime values:
using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic enum ExampleEnum\n{\n Option1,\n Option2,\n Option3,\n}\n\npublic class WShowIfExamples : MonoBehaviour\n{\n public bool toggle;\n\n [WShowIf(nameof(toggle))]\n public string hiddenByBool;\n\n public int intValue;\n\n [WShowIf(nameof(intValue), WShowIfComparison.GreaterThan, 5)]\n public string hiddenByInt;\n\n public ExampleEnum enumValue;\n\n [WShowIf(nameof(enumValue), ExampleEnum.Option2, ExampleEnum.Option3)]\n public string hiddenByEnum;\n}\n\u2192 Full Guide: Inspector Conditional Display
"},{"location":"features/inspector/inspector-overview/#5-selection-dropdowns","title":"5. Selection & Dropdowns","text":"Provide designer-friendly selection controls:
using System.Collections.Generic;\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class WEnumToggleButtonOverview : MonoBehaviour\n{\n [WEnumToggleButtons]\n [IntDropDown(1, 2, 3, 4, 5, 6, 7, 8)]\n public List<int> canToggle; // Works in lists!\n\n [WEnumToggleButtons]\n [IntDropDown(1, 2, 3, 4, 5, 6, 7, 8)]\n public int canToggle2;\n\n [StringInList(typeof(WEnumToggleButtonOverview), nameof(GetStringValues))]\n public string canSelectString;\n\n [WValueDropDown(typeof(WEnumToggleButtonOverview), nameof(GetFloatValues))]\n public float canSelectFloat;\n\n private IEnumerable<string> GetStringValues()\n {\n yield return \"String1\";\n yield return \"String2\";\n yield return \"String3\";\n }\n\n private IEnumerable<float> GetFloatValues()\n {\n yield return 1.0f;\n yield return 2.0f;\n yield return 3.0f;\n }\n}\n\u2192 Full Guide: Inspector Selection Attributes
"},{"location":"features/inspector/inspector-overview/#6-validation-protection","title":"6. Validation & Protection","text":"Protect data integrity with validation attributes:
CheckForNulls()\u2192 Full Guide: Inspector Validation Attributes
"},{"location":"features/inspector/inspector-overview/#7-serialization-types","title":"7. Serialization Types","text":"Unity-friendly wrappers for complex data:
\u2192 Full Guide: Serialization Types
"},{"location":"features/inspector/inspector-overview/#8-project-settings","title":"8. Project Settings","text":"Centralized configuration for all inspector features:
Location: ProjectSettings/UnityHelpersSettings.asset
Settings:
using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class WButtonSettingsExample : MonoBehaviour\n{\n [WButton(colorKey: \"Documentation Example\")]\n private void Button() { }\n}\n\u2192 Full Guide: Inspector Settings
"},{"location":"features/inspector/inspector-overview/#quick-start-example","title":"Quick Start Example","text":"Here's a complete example showcasing multiple inspector features together:
C#using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\nusing WallstopStudios.UnityHelpers.Core.DataStructure.Adapters;\n\npublic class CharacterStats : MonoBehaviour\n{\n // Grouped fields with collapsible sections\n [WGroup(\"Combat\", \"Combat Stats\", collapsible: true)]\n public float maxHealth = 100f; // In group\n public float defense = 10f; // In group (auto-included)\n [WGroupEnd(\"Combat\")] // attackPower IS included, then closes\n public float attackPower = 25f; // In group (last field)\n\n // Conditional visibility based on enum\n public enum WeaponType { Melee, Ranged, Magic }\n public WeaponType weaponType;\n\n [WShowIf(nameof(weaponType), WShowIfComparison.Equal, WeaponType.Ranged)]\n public int ammoCapacity = 30;\n\n // Flag enum as toggle buttons\n [System.Flags]\n public enum Abilities { None = 0, Jump = 1, Dash = 2, Block = 4 }\n\n [WEnumToggleButtons(showSelectAll: true)]\n public Abilities unlockedAbilities;\n\n // Serializable collections\n public SerializableDictionary<string, int> stats;\n public WGuid entityId = WGuid.NewGuid();\n\n // Inspector button\n [WButton(\"Reset Stats\")]\n private void ResetStats() => maxHealth = defense = attackPower = 100f;\n}\nFor individual feature examples, see the detailed guides linked above.
"},{"location":"features/inspector/inspector-overview/#feature-comparison","title":"Feature Comparison","text":"Feature Unity Default Odin Inspector Unity Helpers Grouping/Boxes Custom Editor[BoxGroup] [WGroup] Foldouts Custom Editor [FoldoutGroup] [WGroup(collapsible: true)] Method Buttons Custom Editor [Button] [WButton] Conditional Display Custom Drawer [ShowIf] [WShowIf] Enum Toggles Custom Drawer [EnumToggleButtons] [WEnumToggleButtons] Dictionaries Not Supported [ShowInInspector] SerializableDictionary<K,V> Sets Not Supported Custom SerializableHashSet<T> Type References Not Supported Custom SerializableType Nullable Values Not Supported Custom SerializableNullable<T> Color Themes Not Supported Built-in Project Settings Cost Free \\(55-\\)95 Free (MIT)"},{"location":"features/inspector/inspector-overview/#design-philosophy","title":"Design Philosophy","text":"Declarative Over Imperative:
Designer-Friendly:
Performance-Conscious:
Project-Consistent:
Install Unity Helpers - See Installation Guide
Explore Examples - Check the guides linked above
Configure Settings - Open ProjectSettings/UnityHelpersSettings.asset to customize pagination, colors, and animations
Add Attributes - Start with [WGroup] and [WButton] for immediate impact
Use Serialization Types - Replace custom wrappers with SerializableDictionary, SerializableSet, etc.
Next Steps:
Choose a guide based on what you want to learn first:
Transform selection controls from dropdowns to designer-friendly interfaces.
Unity Helpers provides four powerful selection attributes that replace standard dropdowns with toggle buttons, searchable lists, and type-safe selection controls. Perfect for flags, enums, predefined values, and dynamic option lists.
"},{"location":"features/inspector/inspector-selection-attributes/#table-of-contents","title":"Table of Contents","text":"Draws enum and flag enum fields as a toolbar of toggle buttons.
"},{"location":"features/inspector/inspector-selection-attributes/#basic-usage","title":"Basic Usage","text":"C#using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class EntityPermissions : MonoBehaviour\n{\n [System.Flags]\n public enum Permissions\n {\n None = 0,\n Move = 1 << 0,\n Attack = 1 << 1,\n UseItems = 1 << 2,\n CastSpells = 1 << 3,\n }\n\n [WEnumToggleButtons]\n public Permissions currentPermissions = Permissions.Move | Permissions.Attack;\n}\nVisual Reference
Flag enum permissions rendered as toggle buttons
"},{"location":"features/inspector/inspector-selection-attributes/#parameters","title":"Parameters","text":"C#[WEnumToggleButtons(\n int buttonsPerRow = 0, // Force column count (0 = automatic)\n bool showSelectAll = false, // Show \"Select All\" button (flags only)\n bool showSelectNone = false, // Show \"Select None\" button (flags only)\n bool enablePagination = true, // Allow pagination for many options\n int pageSize = -1, // Override page size (defaults to project setting)\n string colorKey = \"Default\" // Color palette key\n)]\n[System.Flags]\npublic enum DamageTypes\n{\n None = 0,\n Physical = 1 << 0,\n Fire = 1 << 1,\n Ice = 1 << 2,\n Lightning = 1 << 3,\n Poison = 1 << 4,\n}\n\n[WEnumToggleButtons(showSelectAll: true, showSelectNone: true, buttonsPerRow: 3)]\npublic DamageTypes resistances = DamageTypes.Fire | DamageTypes.Ice;\nVisual Reference
Flag enum with Select All and Select None quick action buttons
Behavior:
public enum WeaponType { Melee, Ranged, Magic }\n\n[WEnumToggleButtons(buttonsPerRow: 3, colorKey: \"Default-Dark\")]\npublic WeaponType weaponType = WeaponType.Melee;\nVisual Reference
Standard enum rendered as radio-style toggle buttons (only one active)
Behavior:
[System.Flags]\npublic enum AllAbilities\n{\n None = 0,\n Ability1 = 1 << 0,\n Ability2 = 1 << 1,\n // ... 20 more abilities ...\n Ability22 = 1 << 21,\n}\n\n[WEnumToggleButtons(enablePagination: true, pageSize: 10)]\npublic AllAbilities unlockedAbilities;\nVisual Reference
Paginated toggle buttons with First, Previous, Next, Last navigation controls
Features:
pageSize parameter or UnityHelpersSettings.EnumToggleButtonsPageSize// Automatic layout (fits to inspector width)\n[WEnumToggleButtons]\npublic Permissions autoLayout;\n\n// Force 2 columns\n[WEnumToggleButtons(buttonsPerRow: 2)]\npublic Permissions twoColumns;\n\n// Force single column\n[WEnumToggleButtons(buttonsPerRow: 1)]\npublic Permissions singleColumn;\nVisual Reference
Different column layouts: automatic, 2 columns, and single column
"},{"location":"features/inspector/inspector-selection-attributes/#color-theming","title":"Color Theming","text":"C#[WEnumToggleButtons(colorKey: \"Default-Dark\")]\npublic Permissions darkTheme;\n\n[WEnumToggleButtons(colorKey: \"Default-Light\")]\npublic Permissions lightTheme;\nVisual Reference
Toggle buttons with dark and light color themes
"},{"location":"features/inspector/inspector-selection-attributes/#combining-with-other-attributes","title":"Combining with Other Attributes","text":"C#// Works with IntDropDown/StringInList/WValueDropDown!\n[IntDropDown(0, 30, 60, 120)]\n[WEnumToggleButtons]\npublic int frameRate = 60; // Shows as toggle buttons instead of dropdown\nThe drawer intentionally filters out composite flag values (e.g., ReadWrite = Read | Write). This keeps the UI focused on atomic toggles and avoids ambiguous interactions. Use the \"Select All\" and \"Select None\" buttons for bulk operations.
WShowIf to build adaptive, context-aware authoring toolsGeneric dropdown for any type with fixed values or provider methods.
"},{"location":"features/inspector/inspector-selection-attributes/#basic-usage-fixed-values","title":"Basic Usage (Fixed Values)","text":"C#// Primitive types\n[WValueDropDown(0, 25, 50, 100)]\npublic int staminaThreshold = 50;\n\n[WValueDropDown(0.5f, 1.0f, 1.5f, 2.0f)]\npublic float damageMultiplier = 1.0f;\n\n[WValueDropDown(\"Easy\", \"Normal\", \"Hard\", \"Insane\")]\npublic string difficulty = \"Normal\";\nVisual Reference
Dropdown showing predefined integer, float, and string values
"},{"location":"features/inspector/inspector-selection-attributes/#provider-methods","title":"Provider Methods","text":"C#using System.Collections.Generic;\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\n[CreateAssetMenu(fileName = \"PowerUpDefinition\", menuName = \"Power-Up Definition\")]\npublic class PowerUpDefinition : ScriptableObject\n{\n public string name;\n public Sprite icon;\n}\n\npublic class PowerUpConfig : MonoBehaviour\n{\n [WValueDropDown(typeof(PowerUpLibrary), nameof(PowerUpLibrary.GetAvailablePowerUps))]\n public PowerUpDefinition selectedPowerUp;\n}\n\npublic static class PowerUpLibrary\n{\n public static IEnumerable<PowerUpDefinition> GetAvailablePowerUps()\n {\n // Return all power-ups from database/resources/etc.\n return Resources.LoadAll<PowerUpDefinition>(\"PowerUps\");\n }\n}\nVisual Reference
PowerUp definitions loaded from Resources folder
Dropdown populated dynamically from a provider method
"},{"location":"features/inspector/inspector-selection-attributes/#primitive-overloads","title":"Primitive Overloads","text":"C#using System.Collections.Generic;\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class WValueDropDownPrimitives : MonoBehaviour\n{\n // All primitive types supported:\n [WValueDropDown(true, false)] // bool\n public bool boolValue;\n\n [WValueDropDown(true, false)] // bool\n public List<bool> boolValues;\n\n [WValueDropDown('A', 'B', 'C')] // char\n public char charValue;\n\n [WValueDropDown((byte)1, (byte)2, (byte)3)] // byte\n public byte byteValue;\n\n [WValueDropDown((short)10, (short)20, (short)30)] // short\n public short shortValue;\n\n [WValueDropDown(100, 200, 300)] // int\n public int intValue;\n\n [WValueDropDown(1000L, 2000L, 3000L)] // long\n public long longValue;\n\n [WValueDropDown(0.1f, 0.5f, 1.0f)] // float\n public float floatValue;\n\n [WValueDropDown(0.1, 0.5, 1.0)] // double\n public double doubleValue;\n}\nVisual Reference
Multiple dropdowns showing all supported primitive types
"},{"location":"features/inspector/inspector-selection-attributes/#instance-provider-context-aware","title":"Instance Provider (context-aware)","text":"C#public class DynamicOptions : MonoBehaviour\n{\n public string prefix = \"Option\";\n public int optionCount = 5;\n\n // Instance method - uses object state to build options\n [WValueDropDown(nameof(GetAvailableOptions), typeof(string))]\n public string selectedOption;\n\n private IEnumerable<string> GetAvailableOptions()\n {\n for (int i = 1; i <= optionCount; i++)\n {\n yield return $\"{prefix}_{i}\";\n }\n }\n}\nPassing only a method name instructs the drawer to search the decorated type for a parameterless method. Instance methods run on the serialized object; static methods are also supported. The second parameter specifies the value type for proper dropdown rendering.
Alternate Constructor Forms:
C#// Form 1: Instance method with explicit value type\n[WValueDropDown(nameof(GetOptions), typeof(int))]\npublic int selection;\n\n// Form 2: Static provider from external type\n[WValueDropDown(typeof(DataProvider), nameof(DataProvider.GetItems))]\npublic Item selected;\n\n// Form 3: Static provider with explicit value type conversion\n[WValueDropDown(typeof(DataProvider), nameof(DataProvider.GetIds), typeof(int))]\npublic int selectedId;\nusing System;\nusing System.Collections.Generic;\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\n[Serializable]\npublic class Preset\n{\n public string name;\n public float value;\n\n public override string ToString() => name; // Used for dropdown label\n}\n\npublic class Config : MonoBehaviour\n{\n [WValueDropDown(typeof(Config), nameof(GetPresets))]\n public Preset selectedPreset;\n\n public static IEnumerable<Preset> GetPresets()\n {\n return new[]\n {\n new Preset { name = \"Low\", value = 0.5f },\n new Preset { name = \"Medium\", value = 1.0f },\n new Preset { name = \"High\", value = 2.0f },\n };\n }\n}\nVisual Reference
Dropdown showing custom serializable class options using ToString() for labels
"},{"location":"features/inspector/inspector-selection-attributes/#constructor-reference","title":"Constructor Reference","text":"Constructor Use CaseWValueDropDown(params T[] values) Fixed list of primitive values (int, float, string, etc.) WValueDropDown(Type provider, string method) Static or instance method on external type WValueDropDown(Type provider, string method, Type valueType) Provider with explicit value type conversion WValueDropDown(string method, Type valueType) Instance/static method on the decorated type itself WValueDropDown(Type valueType, params object[] values) Fixed list with explicit type specification"},{"location":"features/inspector/inspector-selection-attributes/#best-practices-for-wvaluedropdown","title":"Best Practices for WValueDropDown","text":"ToString() on custom types to control dropdown labelsInteger field rendered as a dropdown with predefined options.
"},{"location":"features/inspector/inspector-selection-attributes/#basic-usage_1","title":"Basic Usage","text":"C#[IntDropDown(0, 30, 60, 120, 240)]\npublic int refreshRate = 60;\n\n[IntDropDown(1, 2, 4, 8, 16, 32)]\npublic int threadCount = 4;\nVisual Reference
Integer dropdown showing predefined frame rate options
"},{"location":"features/inspector/inspector-selection-attributes/#provider-method","title":"Provider Method","text":"C#public class FrameRateConfig : MonoBehaviour\n{\n [IntDropDown(typeof(FrameRateLibrary), nameof(FrameRateLibrary.GetSupportedFrameRates))]\n public int targetFrameRate = 60;\n}\n\npublic static class FrameRateLibrary\n{\n public static IEnumerable<int> GetSupportedFrameRates()\n {\n return new[] { 30, 60, 90, 120, 144, 240 };\n }\n}\n[IntDropDown(10, 20, 30)]\npublic int value = 25; // Not in list! Shows as standard IntField\nNote: If the current value isn't in the list, falls back to standard IntField for editing.
"},{"location":"features/inspector/inspector-selection-attributes/#stringinlist","title":"StringInList","text":"String field constrained to a set of allowed values with an inline dropdown that opens a searchable popup.
"},{"location":"features/inspector/inspector-selection-attributes/#basic-usage_2","title":"Basic Usage","text":"C#[StringInList(\"Easy\", \"Normal\", \"Hard\", \"Nightmare\")]\npublic string difficulty = \"Normal\";\n\n[StringInList(\"Red\", \"Green\", \"Blue\", \"Yellow\", \"Purple\")]\npublic string teamColor = \"Red\";\nVisual Reference
String dropdown with an inline popup showing search bar and results
"},{"location":"features/inspector/inspector-selection-attributes/#provider-method_1","title":"Provider Method","text":"C#public class LocalizationConfig : MonoBehaviour\n{\n [StringInList(typeof(LocalizationKeys), nameof(LocalizationKeys.GetAllKeys))]\n public string dialogKey;\n}\n\npublic static class LocalizationKeys\n{\n public static IEnumerable<string> GetAllKeys()\n {\n // Return keys from localization database\n return new[] { \"DIALOG_GREETING\", \"DIALOG_FAREWELL\", \"DIALOG_QUEST_START\" };\n }\n}\npublic class StateMachine : MonoBehaviour\n{\n [StringInList(nameof(BuildAvailableStates))]\n public string currentState;\n\n private IEnumerable<string> BuildAvailableStates()\n {\n // Instance data drives the dropdown\n yield return $\"{gameObject.name}_Idle\";\n yield return $\"{gameObject.name}_Run\";\n }\n\n public static IEnumerable<string> StaticStates()\n {\n // Static helpers still work when referenced by name\n return new[] { \"Global_A\", \"Global_B\" };\n }\n}\nPassing only a method name instructs the drawer to search the decorated type for a parameterless method. Instance methods run on the serialized object; static methods are also supported.
"},{"location":"features/inspector/inspector-selection-attributes/#search-and-pagination","title":"Search and Pagination","text":"C#[StringInList(typeof(SceneLibrary), nameof(SceneLibrary.GetAllSceneNames))]\npublic string targetScene;\n\npublic static class SceneLibrary\n{\n public static IEnumerable<string> GetAllSceneNames()\n {\n // Return 100+ scene names\n return EditorBuildSettings.scenes.Select(s => s.path);\n }\n}\nWhen the menu contains more entries than the configured limit, clicking the field opens a popup that embeds the search bar and pagination controls directly in the dropdown itself. The inspector row remains single-line, but the popup still supports fast filtering and page navigation.
Visual Reference
Popup window with a search box filtering results in real-time
Features:
UnityHelpersSettings.StringInListPageLimitSerializableTypeDrawer)Scene Names:
C#[StringInList(typeof(SceneHelper), nameof(SceneHelper.GetAllScenes))]\npublic string loadScene;\nAnimation States:
C#[StringInList(\"Idle\", \"Walk\", \"Run\", \"Jump\", \"Attack\")]\npublic string currentAnimation = \"Idle\";\nLocalization Keys:
C#[StringInList(typeof(LocaleManager), nameof(LocaleManager.GetKeys))]\npublic string textKey;\nTag/Layer Names:
C#[StringInList(\"Player\", \"Enemy\", \"Projectile\", \"Environment\")]\npublic string entityTag = \"Player\";\n// \u2705 GOOD: WEnumToggleButtons for flags (visual toggle state)\n[System.Flags]\npublic enum Features { None = 0, Feature1 = 1, Feature2 = 2, Feature3 = 4 }\n\n[WEnumToggleButtons]\npublic Features enabledFeatures;\n\n// \u2705 GOOD: WValueDropDown for fixed type-safe options\n[WValueDropDown(0.5f, 1.0f, 1.5f, 2.0f)]\npublic float speedMultiplier;\n\n// \u2705 GOOD: IntDropDown for integer-specific options\n[IntDropDown(30, 60, 120, 240)]\npublic int frameRate;\n\n// \u2705 GOOD: StringInList for string validation\n[StringInList(\"Easy\", \"Normal\", \"Hard\")]\npublic string difficulty;\n\n// \u274c BAD: Using strings when enum would be better\n[StringInList(\"Easy\", \"Normal\", \"Hard\")]\npublic string difficulty; // Should be an enum!\n// \u2705 GOOD: Provider method for data that changes\n[WValueDropDown(typeof(AssetDatabase), nameof(GetAllPrefabs))]\npublic GameObject prefab;\n\npublic static IEnumerable<GameObject> GetAllPrefabs()\n{\n return Resources.LoadAll<GameObject>(\"Prefabs\");\n}\n\n// \u274c BAD: Hardcoded values for dynamic data\n[WValueDropDown/* hardcoded list of 50 prefabs */]\npublic GameObject prefab; // Nightmare to maintain!\n// \u2705 GOOD: Select All/None for flag enums\n[System.Flags]\npublic enum Permissions { None = 0, Read = 1, Write = 2, Execute = 4 }\n\n[WEnumToggleButtons(showSelectAll: true, showSelectNone: true)]\npublic Permissions permissions;\n\n// \u2705 GOOD: Pagination for many options\n[WEnumToggleButtons(enablePagination: true, pageSize: 10)]\npublic ManyOptionsEnum options;\n\n// \u274c BAD: No pagination with 50 options (cluttered inspector!)\n[WEnumToggleButtons(enablePagination: false)]\npublic ManyOptionsEnum options;\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class Armor : MonoBehaviour\n{\n [System.Flags]\n public enum DamageType\n {\n None = 0,\n Physical = 1 << 0,\n Fire = 1 << 1,\n Ice = 1 << 2,\n Lightning = 1 << 3,\n Poison = 1 << 4,\n Magic = 1 << 5,\n }\n\n [WEnumToggleButtons(showSelectAll: true, showSelectNone: true,\n buttonsPerRow: 3, colorKey: \"Default-Dark\")]\n public DamageType resistances = DamageType.Physical;\n\n [WEnumToggleButtons(showSelectAll: true, showSelectNone: true,\n buttonsPerRow: 3, colorKey: \"Default-Light\")]\n public DamageType vulnerabilities = DamageType.None;\n}\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class GraphicsConfig : MonoBehaviour\n{\n [System.Serializable]\n public class QualityPreset\n {\n public string name;\n public int textureQuality;\n public int shadowDistance;\n\n public override string ToString() => name;\n }\n\n [WValueDropDown(typeof(GraphicsConfig), nameof(GetPresets))]\n public QualityPreset selectedPreset;\n\n public static IEnumerable<QualityPreset> GetPresets()\n {\n return new[]\n {\n new QualityPreset { name = \"Low\", textureQuality = 0, shadowDistance = 50 },\n new QualityPreset { name = \"Medium\", textureQuality = 1, shadowDistance = 100 },\n new QualityPreset { name = \"High\", textureQuality = 2, shadowDistance = 200 },\n new QualityPreset { name = \"Ultra\", textureQuality = 3, shadowDistance = 500 },\n };\n }\n}\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\nusing System.Linq;\n\npublic class SceneLoader : MonoBehaviour\n{\n [StringInList(typeof(SceneLoader), nameof(GetAllSceneNames))]\n public string mainMenuScene;\n\n [StringInList(typeof(SceneLoader), nameof(GetAllSceneNames))]\n public string gameplayScene;\n\n [StringInList(typeof(SceneLoader), nameof(GetAllSceneNames))]\n public string creditsScene;\n\n public static IEnumerable<string> GetAllSceneNames()\n {\n#if UNITY_EDITOR\n return UnityEditor.EditorBuildSettings.scenes\n .Select(s => System.IO.Path.GetFileNameWithoutExtension(s.path));\n#else\n return new string[0];\n#endif\n }\n}\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class PerformanceSettings : MonoBehaviour\n{\n [IntDropDown(30, 60, 90, 120, 144, 240, -1)]\n public int targetFrameRate = 60; // -1 = unlimited\n\n [IntDropDown(0, 1, 2, 3, 4)]\n public int vsyncCount = 0; // 0 = disabled\n\n [WEnumToggleButtons]\n public enum FrameLimitMode { Unlimited, Target, VSync }\n\n public FrameLimitMode limitMode = FrameLimitMode.Target;\n\n private void OnValidate()\n {\n Application.targetFrameRate = targetFrameRate;\n QualitySettings.vSyncCount = vsyncCount;\n }\n}\nNext Steps:
[WEnumToggleButtons] for better UX[StringInList] for scene names, animation states, localization keys[WValueDropDown] for type-safe selection controlsCentralized configuration for all inspector features.
The UnityHelpersSettings asset provides project-wide configuration for pagination, colors, animations, and history capacity across all inspector attributes and custom drawers. Configure once, apply everywhere.
Location: ProjectSettings/UnityHelpersSettings.asset
Access in Unity:
Edit > Project Settings)ProjectSettings/UnityHelpersSettings.asset directlyNote: The asset is created automatically on first use. If missing, any inspector feature will generate it.
"},{"location":"features/inspector/inspector-settings/#pagination-settings","title":"Pagination Settings","text":"Controls how many items are shown per page in various UI elements.
"},{"location":"features/inspector/inspector-settings/#stringinlistpagesize","title":"StringInListPageSize","text":"[StringInList] attributeDescription: Number of string options shown per page in the dropdown.
Usage:
C#[StringInList(typeof(SceneLibrary), nameof(SceneLibrary.GetAllSceneNames))]\npublic string sceneName; // Uses StringInListPageSize\nSerializableHashSet<T>, SerializableSortedSet<T>Description: Number of set elements shown per page in the inspector.
Usage:
C#public SerializableHashSet<string> items; // Uses SerializableSetPageSize\nSerializableHashSet<T>, SerializableSortedSet<T>Description: Controls whether SerializableSet inspectors start collapsed the first time they are drawn. When enabled, sets render as a single foldout header until the user expands them; when disabled, the inspector opens automatically. This is only a default\u2014explicit script/test changes to SerializedProperty.isExpanded or [WSerializableCollectionFoldout] overrides still win.
SerializableDictionary<TKey, TValue>, SerializableSortedDictionary<TKey, TValue>Description: Number of dictionary entries shown per page in the inspector.
Usage:
C#public SerializableDictionary<string, GameObject> prefabs; // Uses SerializableDictionaryPageSize\nSerializableDictionary<TKey, TValue>, SerializableSortedDictionary<TKey, TValue>Description: Determines whether SerializableDictionary inspectors begin collapsed before any user interaction. Disable this to have dictionaries open automatically in newly created inspectors. Like the set toggle, this only establishes the default; [WSerializableCollectionFoldout] or manual changes to SerializedProperty.isExpanded take precedence on a per-field basis.
SerializableHashSet<T>Description: Controls whether the manual entry foldout in SerializableSet inspectors animates when expanding or collapsing.
"},{"location":"features/inspector/inspector-settings/#serializablesetfoldoutspeed","title":"SerializableSetFoldoutSpeed","text":"SerializableHashSet<T>Description: Animation speed for the SerializableSet manual entry foldout when SerializableSetFoldoutTweenEnabled is enabled.
SerializableSortedSet<T>Description: Controls whether the manual entry foldout in SerializableSortedSet inspectors animate when expanding or collapsing.
"},{"location":"features/inspector/inspector-settings/#serializablesortedsetfoldoutspeed","title":"SerializableSortedSetFoldoutSpeed","text":"SerializableSortedSet<T>Description: Animation speed for the SerializableSortedSet manual entry foldout when SerializableSortedSetFoldoutTweenEnabled is enabled.
[WEnumToggleButtons] attribute (when pagination enabled)Description: Number of toggle buttons shown per page for enums with many values.
Usage:
C#[WEnumToggleButtons(enablePagination: true)]\npublic ManyOptionsEnum options; // Uses EnumToggleButtonsPageSize\n[WButton] attribute (grouped by draw order)Description: Number of button actions shown per page.
Usage:
C#[WButton(\"Action 1\", drawOrder: 0)]\nprivate void Action1() { }\n\n// ... 10 more buttons with drawOrder: 0 ...\n// Pagination kicks in after WButtonPageSize buttons\n[WButton] methods with return valuesDescription: Number of recent results to keep per method per target.
Usage:
C#[WButton(\"Roll Dice\")] // Uses WButtonHistorySize\nprivate int RollDice() => Random.Range(1, 7);\n\n[WButton(\"Custom History\", historyCapacity: 20)] // Overrides global setting\nprivate int CustomHistory() => Random.Range(1, 100);\n[WButton] buttons using groupPlacement: WButtonGroupPlacement.UseGlobalSettingDescription: Default placement of buttons in the inspector.
Note: Use the groupPlacement parameter on individual buttons to override this setting:
groupPlacement: WButtonGroupPlacement.Top \u2192 Always render above inspector propertiesgroupPlacement: WButtonGroupPlacement.Bottom \u2192 Always render below inspector propertiesgroupPlacement: WButtonGroupPlacement.UseGlobalSetting \u2192 Follow this global setting (default)[WButton] grouped buttonsDescription: Controls foldout behavior for button groups.
[WButton] grouped buttonsDescription: Enable smooth animation when expanding/collapsing button groups.
"},{"location":"features/inspector/inspector-settings/#wbuttonfoldoutspeed","title":"WButtonFoldoutSpeed","text":"[WButton] grouped buttons (when tween enabled)Description: Animation speed for button group fold/unfold.
[WGroup] attributes using UseGlobalAutoIncludeDescription: Default number of fields to auto-include in a WGroup.
Usage:
C#// Uses WGroupAutoIncludeRowCount (default: 4)\n[WGroup(\"stats\", \"Stats\")]\npublic int strength; // Field 1: in group\npublic int agility; // Field 2: in group (auto-included)\npublic int intelligence; // Field 3: in group (auto-included)\n[WGroupEnd(\"stats\")] // luck IS included (field 4), then group closes\npublic int luck; // Field 4: in group (last field)\n\n// Explicit override\n[WGroup(\"combat\", \"Combat\", autoIncludeCount: 2)]\npublic float health; // Field 1: in group\n[WGroupEnd(\"combat\")] // mana IS included (field 2), then group closes\npublic float mana; // Field 2: in group (last field)\n[WGroup] with collapsible: true when startCollapsed is omittedDescription: Controls the initial foldout state for collapsible WGroups. Disable this to have collapsible groups start expanded unless the attribute explicitly passes startCollapsed: true.
Projects can still override per group via the startCollapsed constructor argument or the CollapseBehavior named argument:
[WGroup(\n \"advanced\",\n collapsible: true,\n CollapseBehavior = WGroupAttribute.WGroupCollapseBehavior.ForceExpanded\n)]\n[WGroup] with collapsible: trueDescription: Enable smooth animation when expanding/collapsing groups.
"},{"location":"features/inspector/inspector-settings/#wgrouptweenspeed","title":"WGroupTweenSpeed","text":"[WGroup] with collapsible: true (when tween enabled)Description: Animation speed for group fold/unfold.
"},{"location":"features/inspector/inspector-settings/#inline-editor-settings","title":"Inline Editor Settings","text":"Controls behavior for the [WInLineEditor] attribute that embeds nested inspectors inline.
[WInLineEditor] without explicit modeDescription: Default foldout behavior for inline editors.
Note: Use the mode parameter on individual attributes to override this setting:
// Uses global setting\n[WInLineEditor]\npublic AbilityConfig config;\n\n// Always shows inline inspector\n[WInLineEditor(WInLineEditorMode.AlwaysExpanded)]\npublic AbilityConfig alwaysVisible;\n\n// Starts collapsed regardless of global setting\n[WInLineEditor(WInLineEditorMode.FoldoutCollapsed)]\npublic AbilityConfig collapsedByDefault;\n[WInLineEditor] with foldout modesDescription: Enable smooth animation when expanding/collapsing inline editors.
"},{"location":"features/inspector/inspector-settings/#inlineeditorfoldoutspeed","title":"InlineEditorFoldoutSpeed","text":"[WInLineEditor] with foldout modes (when tween enabled)Description: Animation speed for inline editor fold/unfold.
Palette keys keep WButton and WEnumToggleButtons visuals consistent across the project. Open the Color Palettes foldout inside UnityHelpersSettings to add or edit entries. Each key is matched at draw time against the colorKey parameter on the corresponding attribute; unknown keys fall back to theme-aware defaults.
[WButton] via the colorKey parameterDefault, Default-Light, Default-Dark, WDefault (legacy)Usage:
Highlight) and pick button/text colors.[WButton(\"Submit\", colorKey: \"Highlight\")]\nprivate void Submit() { }\n[WEnumToggleButtons] via the ColorKey propertyDefault, Default-Light, Default-DarkUsage: Add a key under WEnumToggleButtons Custom Colors, then assign it per field:
C#[WEnumToggleButtons(ColorKey = \"Difficulty\")]\npublic DifficultyLevel difficulty;\nSee Pagination Settings.
"},{"location":"features/inspector/inspector-settings/#creating-the-settings-asset","title":"Creating the Settings Asset","text":"The UnityHelpersSettings asset is automatically created on first use, but you can create it manually:
ProjectSettings/UnityHelpersSettings.asset#if UNITY_EDITOR\nusing WallstopStudios.UnityHelpers.Editor.Settings;\n\nUnityHelpersSettings settings = UnityHelpersSettings.Instance;\n// Settings asset is now created\n#endif\nStringInListPageSize: 50\nSerializableSetPageSize: 30\nEnumToggleButtonsPageSize: 25\nWButtonPageSize: 12\nUse case: Large monitors, scrolling preference over pagination
"},{"location":"features/inspector/inspector-settings/#low-density-ui-fewer-items-per-page","title":"Low-Density UI (Fewer items per page)","text":"Text OnlyStringInListPageSize: 10\nSerializableSetPageSize: 5\nEnumToggleButtonsPageSize: 8\nWButtonPageSize: 4\nUse case: Laptop screens, prefer focused views
"},{"location":"features/inspector/inspector-settings/#performance-focused-disable-animations","title":"Performance-Focused (Disable animations)","text":"Text OnlyWButtonFoldoutTweenEnabled: false\nWGroupTweenEnabled: false\nInlineEditorFoldoutTweenEnabled: false\nUse case: Slower machines, prefer instant feedback
"},{"location":"features/inspector/inspector-settings/#smooth-animations-fast-tweens","title":"Smooth Animations (Fast tweens)","text":"Text OnlyWButtonFoldoutSpeed: 8.0\nWGroupTweenSpeed: 8.0\nInlineEditorFoldoutSpeed: 8.0\nUse case: Snappy UI feel
"},{"location":"features/inspector/inspector-settings/#extensive-history-more-button-results","title":"Extensive History (More button results)","text":"Text OnlyWButtonHistorySize: 10\nUse case: Heavy testing/debugging workflows
"},{"location":"features/inspector/inspector-settings/#troubleshooting","title":"Troubleshooting","text":""},{"location":"features/inspector/inspector-settings/#settings-asset-missing","title":"Settings Asset Missing","text":"Problem: Can't find UnityHelpersSettings.asset
Solution:
ProjectSettings/UnityHelpersSettings.assetProblem: Modified settings but inspector doesn't update
Solution:
Ctrl+S or Cmd+S)Assets > Reimport All)Problem: Custom color key doesn't apply
Solution:
Next Steps:
Protect your data with declarative validation and read-only presentation.
Unity Helpers provides validation attributes that help maintain data integrity and prevent accidental modifications. These attributes work seamlessly with the Unity inspector and can validate fields at runtime.
"},{"location":"features/inspector/inspector-validation-attributes/#table-of-contents","title":"Table of Contents","text":"Displays a field in the inspector as read-only, preventing accidental modifications while keeping the value visible.
"},{"location":"features/inspector/inspector-validation-attributes/#basic-usage","title":"Basic Usage","text":"C#using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class GameManagerReadOnly : MonoBehaviour\n{\n [WReadOnly]\n public string sessionId = \"abc-123-xyz\";\n\n [WReadOnly]\n public float elapsedTime = 0f;\n\n [WReadOnly]\n [SerializeField]\n private int internalScore = 100;\n}\nBehavior:
Visual Reference
Fields marked with [WReadOnly] appear grayed out and cannot be edited
"},{"location":"features/inspector/inspector-validation-attributes/#common-use-cases","title":"Common Use Cases","text":"C#using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class EntityReadOnly : MonoBehaviour\n{\n // Auto-generated unique identifier\n [WReadOnly]\n public string entityId = System.Guid.NewGuid().ToString();\n\n // Computed property exposed for debugging\n [WReadOnly]\n [SerializeField]\n private float _currentHealth;\n\n // Reference that should only be set via code\n [WReadOnly]\n public Transform cachedTarget;\n\n // Frame counter for debugging\n [WReadOnly]\n public int framesSinceLastUpdate;\n}\nWhy Use WReadOnly:
Visual Reference
Multiple field types (string, float, Transform, int) displayed as read-only
"},{"location":"features/inspector/inspector-validation-attributes/#wnotnull","title":"WNotNull","text":"Validates that a field is not null, providing both visual inspector feedback and runtime validation. When a field marked with [WNotNull] is null, the inspector displays a warning or error HelpBox. Additionally, calling CheckForNulls() on an object will throw an ArgumentNullException for any null [WNotNull] fields.
using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class PlayerControllerNotNull : MonoBehaviour\n{\n [WNotNull]\n public Rigidbody2D rb;\n\n [WNotNull]\n public SpriteRenderer spriteRenderer;\n\n [WNotNull]\n [SerializeField]\n private AudioSource audioSource;\n\n private void Awake()\n {\n // Validates all [WNotNull] fields are assigned\n // Throws ArgumentNullException if any are null in Editor ONLY\n this.CheckForNulls();\n }\n}\nBehavior:
this.CheckForNulls() to validate all [WNotNull] fieldsArgumentNullException with the field name if any marked field is nullObject types and plain C# objectsVisual Reference
Fields marked with [WNotNull] display a HelpBox in the inspector when null
"},{"location":"features/inspector/inspector-validation-attributes/#wnotnullmessagetype-enum","title":"WNotNullMessageType Enum","text":"The WNotNullMessageType enum controls how null fields are displayed in the inspector:
Warning Displays a yellow warning HelpBox (default) Error Displays a red error HelpBox"},{"location":"features/inspector/inspector-validation-attributes/#constructor-overloads","title":"Constructor Overloads","text":"The [WNotNull] attribute supports multiple constructor overloads for flexibility:
// Default: warning message type with auto-generated message\n[WNotNull]\npublic GameObject target;\n// Inspector shows: \"target must be assigned\"\n// Error message type with auto-generated message\n[WNotNull(WNotNullMessageType.Error)]\npublic AudioSource criticalAudioSource;\n// Inspector shows red error: \"criticalAudioSource must be assigned\"\n// Warning with custom message\n[WNotNull(\"Player needs a target to attack\")]\npublic Transform attackTarget;\n// Inspector shows yellow warning: \"Player needs a target to attack\"\n// Error with custom message\n[WNotNull(WNotNullMessageType.Error, \"Audio source is required for sound effects\")]\npublic AudioSource audioSource;\n// Inspector shows red error: \"Audio source is required for sound effects\"\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class EnemyAI : MonoBehaviour\n{\n // Yellow warning - nice to have\n [WNotNull]\n public ParticleSystem hitEffect;\n\n // Red error - critical reference\n [WNotNull(WNotNullMessageType.Error)]\n public Transform patrolPath;\n\n // Warning with helpful context\n [WNotNull(\"Assign the player tag or the enemy won't detect the player\")]\n public string playerTag;\n\n // Error with specific instructions\n [WNotNull(WNotNullMessageType.Error, \"Drag the NavMeshAgent component here - required for movement\")]\n public UnityEngine.AI.NavMeshAgent agent;\n}\nVisual Reference
Warning (yellow) and Error (red) HelpBoxes for null fields in the inspector
"},{"location":"features/inspector/inspector-validation-attributes/#runtime-validation-with-checkfornulls","title":"Runtime Validation with CheckForNulls()","text":"The CheckForNulls() extension method validates all [WNotNull] fields at runtime:
using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class EnemySpawner : MonoBehaviour\n{\n [WNotNull]\n public GameObject enemyPrefab;\n\n [WNotNull]\n public Transform spawnPoint;\n\n [WNotNull(WNotNullMessageType.Error)]\n public EnemyManager enemyManager;\n\n private void Start()\n {\n // If any [WNotNull] field is null, this throws with the field name\n // Example: ArgumentNullException(\"enemyPrefab\")\n this.CheckForNulls();\n\n // Safe to use - we know these are assigned\n SpawnEnemy();\n }\n\n private void SpawnEnemy()\n {\n GameObject enemy = Instantiate(enemyPrefab, spawnPoint.position, Quaternion.identity);\n enemyManager.RegisterEnemy(enemy);\n }\n}\nBoth the inspector HelpBox display and the CheckForNulls() extension method are only active in the Unity Editor:
// The validation code only runs in UNITY_EDITOR\n// In builds, CheckForNulls() does nothing (stripped for performance)\nthis.CheckForNulls();\nThis means:
public class UIManager : MonoBehaviour\n{\n // Required reference with error severity - validated at runtime\n [WNotNull(WNotNullMessageType.Error)]\n [SerializeField]\n private Canvas mainCanvas;\n\n // Optional reference - not validated\n [SerializeField]\n private AudioSource clickSound;\n\n // Read-only and required\n [WReadOnly]\n [WNotNull]\n public RectTransform cachedRect;\n\n // Group with validation and custom message\n [WGroup(\"UI Elements\")]\n [WNotNull(\"Start button required for main menu\")]\n public Button startButton; // In group\n\n [WNotNull(WNotNullMessageType.Error, \"Quit button required for main menu\")]\n [WGroupEnd(\"UI Elements\")] // quitButton IS included, then closes\n public Button quitButton; // In group (last field)\n}\nWhy Use WNotNull:
CheckForNulls(), not when first usedValidates that a field is properly assigned, providing visual inspector feedback when validation fails. Unlike [WNotNull] which only checks for null references, [ValidateAssignment] validates that fields are \"properly assigned\" based on their type\u2014including checking for empty strings, empty collections, and null references.
Object references Not null Strings Not null or whitespace IList (arrays, List) Has at least one element ICollection Has at least one element IEnumerable Has at least one element Other types Not null"},{"location":"features/inspector/inspector-validation-attributes/#basic-usage_2","title":"Basic Usage","text":"C#using System.Collections.Generic;\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class EnemySpawner : MonoBehaviour\n{\n [ValidateAssignment]\n public GameObject enemyPrefab;\n\n [ValidateAssignment]\n public string enemyName;\n\n [ValidateAssignment]\n public List<Transform> spawnPoints;\n\n private void Start()\n {\n // Logs warnings for any invalid [ValidateAssignment] fields\n this.ValidateAssignments();\n }\n}\nBehavior:
this.ValidateAssignments() to log warnings for invalid fieldsthis.AreAnyAssignmentsInvalid() to check if any fields are invalidObject types, strings, collections, and any reference typeVisual Reference
Fields marked with [ValidateAssignment] display a HelpBox in the inspector when invalid
"},{"location":"features/inspector/inspector-validation-attributes/#validateassignmentmessagetype-enum","title":"ValidateAssignmentMessageType Enum","text":"The ValidateAssignmentMessageType enum controls how invalid fields are displayed in the inspector:
Warning Displays a yellow warning HelpBox (default) Error Displays a red error HelpBox"},{"location":"features/inspector/inspector-validation-attributes/#constructor-overloads_1","title":"Constructor Overloads","text":"The [ValidateAssignment] attribute supports multiple constructor overloads for flexibility:
// Default: warning message type with auto-generated message\n[ValidateAssignment]\npublic GameObject target;\n// Inspector shows: \"target must be assigned\"\n// Error message type with auto-generated message\n[ValidateAssignment(ValidateAssignmentMessageType.Error)]\npublic AudioSource criticalAudioSource;\n// Inspector shows red error: \"criticalAudioSource must be assigned\"\n// Warning with custom message\n[ValidateAssignment(\"Enemy name is required for UI display\")]\npublic string enemyName;\n// Inspector shows yellow warning: \"Enemy name is required for UI display\"\n// Error with custom message\n[ValidateAssignment(ValidateAssignmentMessageType.Error, \"Spawn points list cannot be empty\")]\npublic List<Transform> spawnPoints;\n// Inspector shows red error: \"Spawn points list cannot be empty\"\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\nusing System.Collections.Generic;\n\npublic class GameConfig : MonoBehaviour\n{\n // Yellow warning - validates not null\n [ValidateAssignment]\n public GameObject playerPrefab;\n\n // Red error - validates string not empty/whitespace\n [ValidateAssignment(ValidateAssignmentMessageType.Error)]\n public string gameTitle;\n\n // Warning with helpful context - validates list not empty\n [ValidateAssignment(\"Add at least one difficulty level\")]\n public List<string> difficultyLevels;\n\n // Error with specific instructions - validates array not empty\n [ValidateAssignment(ValidateAssignmentMessageType.Error, \"Spawn points are required - add Transform references\")]\n public Transform[] spawnPoints;\n}\nVisual Reference
Warning (yellow) and Error (red) HelpBoxes for various invalid field types
"},{"location":"features/inspector/inspector-validation-attributes/#runtime-validation-methods","title":"Runtime Validation Methods","text":"Two extension methods are available for runtime validation of [ValidateAssignment] fields:
Logs warnings to the console for all invalid fields:
C#using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class LevelManager : MonoBehaviour\n{\n [ValidateAssignment]\n public GameObject[] enemyPrefabs;\n\n [ValidateAssignment]\n public string levelName;\n\n private void Start()\n {\n // Logs a warning for each invalid [ValidateAssignment] field\n this.ValidateAssignments();\n }\n}\nReturns true if any [ValidateAssignment] field is invalid:
using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class SpawnManager : MonoBehaviour\n{\n [ValidateAssignment]\n public GameObject spawnPrefab;\n\n [ValidateAssignment]\n public List<Transform> spawnLocations;\n\n private void Start()\n {\n if (this.AreAnyAssignmentsInvalid())\n {\n Debug.LogError(\"SpawnManager has invalid assignments - spawning disabled\");\n enabled = false;\n return;\n }\n\n // Safe to proceed - all assignments are valid\n SpawnEnemies();\n }\n}\nBoth attributes validate fields and provide inspector feedback, but they serve different purposes:
Feature ValidateAssignment WNotNull Null object check \u2713 \u2713 Empty string check \u2713 \u2717 Empty collection check \u2713 \u2717 Runtime behavior Logs warnings ThrowsArgumentNullException Best for Comprehensive field validation Strict null reference checking When to use which:
[ValidateAssignment] when you need to validate that strings are non-empty or collections have elements[WNotNull] when you want strict null checking with an exception thrown at runtime[ValidateAssignment] when you want softer runtime validation (warnings instead of exceptions)[WNotNull] for critical references where the game should fail fast if not assignedpublic class PlayerSetup : MonoBehaviour\n{\n // Use WNotNull for critical references - throws if null\n [WNotNull(WNotNullMessageType.Error)]\n public Rigidbody2D rb;\n\n // Use ValidateAssignment for string validation\n [ValidateAssignment]\n public string playerName;\n\n // Use ValidateAssignment for collection validation\n [ValidateAssignment(ValidateAssignmentMessageType.Error, \"Add at least one weapon\")]\n public List<GameObject> startingWeapons;\n\n private void Awake()\n {\n // Throws ArgumentNullException if rb is null\n this.CheckForNulls();\n\n // Logs warnings if playerName is empty or startingWeapons is empty\n this.ValidateAssignments();\n }\n}\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\nusing System.Collections.Generic;\n\npublic class UIManager : MonoBehaviour\n{\n // Group with validation\n [WGroup(\"Required UI Elements\")]\n [ValidateAssignment(ValidateAssignmentMessageType.Error)]\n public Canvas mainCanvas; // In group\n\n [ValidateAssignment(\"Button text cannot be empty\")]\n public string startButtonText; // In group (auto-included)\n\n [ValidateAssignment(ValidateAssignmentMessageType.Error, \"Add menu items to display\")]\n [WGroupEnd(\"Required UI Elements\")] // menuItems IS included, then closes\n public List<GameObject> menuItems; // In group (last field)\n\n // Conditional validation\n [WShowIf(nameof(useCustomTheme))]\n [ValidateAssignment(\"Custom theme name required when using custom theme\")]\n public string customThemeName;\n\n public bool useCustomTheme;\n}\nWhy Use ValidateAssignment:
ValidateAssignments() for warnings instead of exceptionsAreAnyAssignmentsInvalid() for conditional logicCall CheckForNulls() and ValidateAssignments() in Awake() or Start() to catch missing references immediately:
private void Awake()\n{\n // Throws for critical null references\n this.CheckForNulls();\n // Logs warnings for empty strings, collections, etc.\n this.ValidateAssignments();\n}\n// Use WNotNull for critical object references (throws on null)\n[WNotNull(WNotNullMessageType.Error)]\npublic Rigidbody2D rb;\n\n// Use ValidateAssignment for strings (validates not empty/whitespace)\n[ValidateAssignment]\npublic string playerName;\n\n// Use ValidateAssignment for collections (validates not empty)\n[ValidateAssignment(ValidateAssignmentMessageType.Error)]\npublic List<Transform> waypoints;\n[WReadOnly]\npublic float Speed => rb.velocity.magnitude;\n// Auto-wired but protected from manual changes\n[WReadOnly]\n[SiblingComponent]\npublic Collider2D col;\n// Required: Must be assigned in inspector\n[WNotNull]\npublic AudioClip attackSound;\n\n// Required: Must not be empty\n[ValidateAssignment]\npublic string characterName;\n\n// Optional: May be null\npublic AudioClip hitSound;\n[CreateAssetMenu]\npublic class GameConfig : ScriptableObject\n{\n [WNotNull]\n public GameObject playerPrefab;\n\n [WNotNull]\n public Material defaultMaterial;\n\n [ValidateAssignment(\"Game title cannot be empty\")]\n public string gameTitle;\n\n [ValidateAssignment(ValidateAssignmentMessageType.Error)]\n public List<string> supportedLanguages;\n\n private void OnEnable()\n {\n this.CheckForNulls();\n this.ValidateAssignments();\n }\n}\nDrop-in MonoBehaviour components that solve common game development problems without writing custom scripts. Add them to GameObjects for instant functionality like motion animation, collision forwarding, transform following, and visual state management.
"},{"location":"features/inspector/utility-components/#contents","title":"Contents","text":"What it does: Automatically moves a GameObject in a circular or elliptical pattern. Think \"floating pickup\" or \"idle hover animation\" without animators.
Problem it solves: Creating simple repetitive motion (hovering, bobbing, orbiting) usually requires animation curves or custom update loops. Oscillator handles it with three parameters.
"},{"location":"features/inspector/utility-components/#when-to-use","title":"When to Use","text":"\u2705 Use for:
\u274c Don't use for:
Oscillator component to any GameObjectusing WallstopStudios.UnityHelpers.Utils;\n\n// Via code\nOscillator osc = gameObject.AddComponent<Oscillator>();\nosc.speed = 2f; // Two radians/second\nosc.width = 1f; // \u00b11 unit horizontally\nosc.height = 0.5f; // \u00b10.5 units vertically\nGentle hover (coin pickup):
Text Onlyspeed = 3\nwidth = 0\nheight = 0.2\nFigure-8 motion:
Text Onlyspeed = 2\nwidth = 1\nheight = 1\nHorizontal sway:
Text Onlyspeed = 1\nwidth = 0.5\nheight = 0\ntransform.localPosition in Update()What it does: Conditionally instantiates prefabs as children based on environment (editor/development/release) with automatic duplicate prevention.
Problem it solves: Managing debug overlays, analytics, or development tools that should only exist in certain builds. Handles deduplication across scene loads and DontDestroyOnLoad scenarios.
"},{"location":"features/inspector/utility-components/#when-to-use_1","title":"When to Use","text":"\u2705 Use for:
\u274c Don't use for:
Add ChildSpawner to a GameObject (often on a scene manager or empty GameObject):
Inspector configuration:
using WallstopStudios.UnityHelpers.Utils;\n\n// Via code\nChildSpawner spawner = gameObject.AddComponent<ChildSpawner>();\nspawner._prefabs = new[] { analyticsPrefab };\nspawner._developmentOnlyPrefabs = new[] { debugMenuPrefab };\nspawner._spawnMethod = ChildSpawnMethod.Awake;\nspawner._dontDestroyOnLoad = true;\nChildSpawner prevents duplicate instantiation:
C#// Spawns DebugCanvas once\nChildSpawner spawner1 = obj1.AddComponent<ChildSpawner>();\nspawner1._prefabs = new[] { debugCanvasPrefab };\n\n// This will NOT spawn a second DebugCanvas (detects existing instance)\nChildSpawner spawner2 = obj2.AddComponent<ChildSpawner>();\nspawner2._prefabs = new[] { debugCanvasPrefab };\nDeduplication uses prefab asset path matching.
"},{"location":"features/inspector/utility-components/#spawn-methods","title":"Spawn Methods","text":"When enabled:
Typical use case:
Text OnlyScene 1: ChildSpawner spawns AnalyticsManager with DontDestroyOnLoad\nScene 2 loads: Same ChildSpawner detects existing AnalyticsManager, doesn't spawn duplicate\nWhat it does: Exposes Unity's 2D collision callbacks as C# events, enabling composition-based collision handling without inheriting from MonoBehaviour.
Problem it solves: To receive collision events in Unity, you traditionally override OnCollisionEnter2D etc. in a MonoBehaviour subclass. CollisionProxy lets you subscribe to events instead, supporting multiple listeners and decoupled architectures.
\u2705 Use for:
\u274c Don't use for:
CollisionProxy to GameObject with Collider2Dusing WallstopStudios.UnityHelpers.Utils;\n\nCollisionProxy proxy = gameObject.AddComponent<CollisionProxy>();\n\n// Subscribe to enter event\nproxy.OnCollisionEnter += HandleCollision;\nproxy.OnTriggerEnter += HandleTrigger;\n\nvoid HandleCollision(Collision2D collision)\n{\n Debug.Log($\"Hit {collision.gameObject.name}\");\n}\n\nvoid HandleTrigger(Collider2D other)\n{\n Debug.Log($\"Triggered by {other.gameObject.name}\");\n}\n\n// Cleanup\nvoid OnDestroy()\n{\n proxy.OnCollisionEnter -= HandleCollision;\n proxy.OnTriggerEnter -= HandleTrigger;\n}\nCollision events (Collision2D parameter):
OnCollisionEnterOnCollisionStayOnCollisionExitTrigger events (Collider2D parameter):
OnTriggerEnterOnTriggerStayOnTriggerExit// Health system subscribes\nhealthSystem.OnDamageTaken += proxy.OnCollisionEnter;\n\n// Sound system subscribes to same event\nsoundSystem.PlayImpactSound += proxy.OnCollisionEnter;\n\n// Analytics subscribes\nanalytics.TrackCollision += proxy.OnCollisionEnter;\n\n// All three systems react to the same collision independently\nWhat it does: Visualizes CircleCollider2D with a dynamically drawn circle using LineRenderer, with randomized appearance for visual variety.
Problem it solves: Seeing collision bounds at runtime for debugging, or creating dynamic range indicators (ability ranges, explosion radii) without pre-made sprites.
"},{"location":"features/inspector/utility-components/#when-to-use_3","title":"When to Use","text":"\u2705 Use for:
\u274c Don't use for:
CircleLineRenderer to GameObject with CircleCollider2Dusing WallstopStudios.UnityHelpers.Utils;\n\nCircleLineRenderer circleVis = gameObject.AddComponent<CircleLineRenderer>();\ncircleVis.color = Color.red;\ncircleVis.minLineWidth = 0.05f;\ncircleVis.maxLineWidth = 0.15f;\ncircleVis.updateRateSeconds = 0.5f; // Refresh twice per second\nLower values = more frequent randomization = more visual variety but higher CPU cost
Text Only0.1f = Very active (10 updates/sec)\n0.5f = Moderate (2 updates/sec)\n2.0f = Subtle (0.5 updates/sec)\nWhat it does: Makes one transform follow another with configurable update timing and offset.
Problem it solves: Following transforms (UI name plates, camera targets, position constraints) usually require custom scripts. MatchTransform handles it declaratively.
"},{"location":"features/inspector/utility-components/#when-to-use_4","title":"When to Use","text":"\u2705 Use for:
\u274c Don't use for:
using WallstopStudios.UnityHelpers.Utils;\n\nMatchTransform matcher = uiPlate.AddComponent<MatchTransform>();\nmatcher.toMatch = enemyTransform;\nmatcher.localOffset = new Vector3(0, 2, 0); // 2 units above target\nmatcher.mode = MatchTransform.Mode.LateUpdate; // Update after camera\n// Offset is added to target position\nmatcher.localOffset = new Vector3(1, 0, 0); // 1 unit to the right\nIf toMatch is the same GameObject, applies offset once then disables:
matcher.toMatch = transform; // Self-reference\nmatcher.localOffset = new Vector3(5, 0, 0);\n// GameObject moves 5 units right once, then MatchTransform disables itself\n"},{"location":"features/inspector/utility-components/#spriterenderersync","title":"SpriteRendererSync","text":"
What it does: Mirrors one SpriteRenderer's properties (sprite, color, material, sorting) to another, with selective property matching.
Problem it solves: Creating shadow sprites, duplicate renderers for effects, or layered rendering often requires manually keeping multiple SpriteRenderers in sync.
"},{"location":"features/inspector/utility-components/#when-to-use_5","title":"When to Use","text":"\u2705 Use for:
\u274c Don't use for:
using WallstopStudios.UnityHelpers.Utils;\n\n// On the \"follower\" sprite renderer\nSpriteRendererSync syncer = shadowRenderer.AddComponent<SpriteRendererSync>();\nsyncer.toMatch = characterRenderer;\nsyncer.matchColor = false; // Don't copy color (shadow should be black)\nsyncer.matchMaterial = true;\nsyncer.matchSortingLayer = true;\nsyncer.matchOrderInLayer = true;\nWhat to sync:
matchColor: Copy color tintmatchMaterial: Copy materialmatchSortingLayer: Copy sorting layermatchOrderInLayer: Copy order in layerDynamic source:
C#// Change what to match at runtime\nsyncer.DynamicToMatch = () => GetCurrentWeaponRenderer();\nSorting override:
C#// Override order in layer dynamically\nsyncer.DynamicSortingOrderOverride = () => characterRenderer.sortingOrder - 1; // Always behind\nSyncs in LateUpdate() to ensure source renderer has updated first.
// Create shadow GameObject\nGameObject shadow = new GameObject(\"Shadow\");\nshadow.transform.parent = character.transform;\nshadow.transform.localPosition = new Vector3(0.2f, -0.2f, 0); // Offset\n\nSpriteRenderer shadowRenderer = shadow.AddComponent<SpriteRenderer>();\nSpriteRendererSync syncer = shadow.AddComponent<SpriteRendererSync>();\n\nsyncer.toMatch = character.GetComponent<SpriteRenderer>();\nsyncer.matchColor = false;\nshadowRenderer.color = new Color(0, 0, 0, 0.5f); // Semi-transparent black\nWhat it does: Stack-based color and material management for SpriteRenderers, allowing multiple systems to modify visuals with automatic priority handling and restoration.
Problem it solves: When multiple systems want to modify a sprite's color (damage flash, power-up glow, status effect) simultaneously, manually coordinating who \"owns\" the color is error-prone. This provides push/pop semantics with component-based ownership.
"},{"location":"features/inspector/utility-components/#when-to-use_6","title":"When to Use","text":"\u2705 Use for:
\u274c Don't use for:
using WallstopStudios.UnityHelpers.Utils;\n\nSpriteRenderer renderer = GetComponent<SpriteRenderer>();\nSpriteRendererMetadata metadata = renderer.GetComponent<SpriteRendererMetadata>();\nif (metadata == null)\n metadata = renderer.gameObject.AddComponent<SpriteRendererMetadata>();\n\n// Component A pushes red color\nmetadata.PushColor(this, Color.red);\n\n// Component B pushes blue color (takes precedence)\nmetadata.PushColor(otherComponent, Color.blue);\n// Renderer is now blue\n\n// Component B pops its color\nmetadata.PopColor(otherComponent);\n// Renderer reverts to red (Component A's color)\n\n// Component A pops its color\nmetadata.PopColor(this);\n// Renderer reverts to original color\nPush/Pop (LIFO - Last In, First Out):
C#metadata.PushColor(owner, Color.red); // Add to top of stack\nmetadata.PopColor(owner); // Remove from top (must match owner)\nPushBack (add to bottom, lower priority):
C#metadata.PushBackColor(owner, Color.yellow); // Added to bottom, doesn't change current color unless stack is empty\nEach color/material is tagged with the Component that pushed it:
C#public class DamageFlash : MonoBehaviour\n{\n void OnDamage()\n {\n metadata.PushColor(this, Color.red);\n Invoke(nameof(RemoveFlash), 0.1f);\n }\n\n void RemoveFlash()\n {\n metadata.PopColor(this); // Only removes if this component owns top of stack\n }\n}\nThis prevents Component A from accidentally removing Component B's color.
"},{"location":"features/inspector/utility-components/#material-stacking","title":"Material Stacking","text":"Works identically for materials:
C#metadata.PushMaterial(this, glowMaterial);\n// ... later\nmetadata.PopMaterial(this);\nColor original = metadata.OriginalColor; // Color before any modifications\nColor current = metadata.CurrentColor; // Current top-of-stack color\n\nMaterial originalMat = metadata.OriginalMaterial;\nMaterial currentMat = metadata.CurrentMaterial;\nAwake()What it does: Defines a logical center point for a GameObject that's separate from the transform pivot, scaled by the object's local scale.
Problem it solves: Sprites with off-center pivots (for animation reasons) need a separate \"logical center\" for gameplay (rotation point, targeting reticle, etc.). This provides that without changing the transform pivot.
"},{"location":"features/inspector/utility-components/#when-to-use_7","title":"When to Use","text":"\u2705 Use for:
\u274c Don't use for:
using WallstopStudios.UnityHelpers.Utils;\n\nCenterPointOffset centerDef = gameObject.AddComponent<CenterPointOffset>();\ncenterDef.offset = new Vector2(0, 0.5f); // Center is 0.5 units above transform\ncenterDef.spriteUsesOffset = true; // Flag for sprite-specific logic\n\n// Get world-space center point\nVector2 centerInWorld = centerDef.CenterPoint;\n\n// Use for targeting\ntargetingSystem.AimAt(centerDef.CenterPoint);\nOffset is multiplied by transform.localScale:
transform.position = (0, 0)\noffset = (1, 0)\ntransform.localScale = (2, 2, 2)\n\nCenterPoint = (0, 0) + (1, 0) * (2, 2) = (2, 0)\nThis ensures the center point scales with the object.
"},{"location":"features/inspector/utility-components/#sprite-flag","title":"Sprite Flag","text":"spriteUsesOffset is a boolean flag you can check in other systems:
if (center.spriteUsesOffset)\n{\n // Apply sprite-specific logic\n}\nWhat it does: Type-safe, enum-based Animator state control. Maps enum values to Animator boolean parameters for exclusive state control.
Problem it solves: Setting Animator bools with magic strings (animator.SetBool(\"IsJumping\", true)) is error-prone and hard to refactor. This provides compile-time safety and automatic cleanup of previous states.
\u2705 Use for:
\u274c Don't use for:
1. Define an enum matching your Animator parameters:
C#public enum PlayerState\n{\n Idle, // Maps to Animator bool \"Idle\"\n Running, // Maps to Animator bool \"Running\"\n Jumping, // Maps to Animator bool \"Jumping\"\n Falling // Maps to Animator bool \"Falling\"\n}\n2. Create the state machine:
C#using WallstopStudios.UnityHelpers.Utils;\n\nAnimator animator = GetComponent<Animator>();\nAnimatorEnumStateMachine<PlayerState> stateMachine;\n\nvoid Awake()\n{\n stateMachine = new AnimatorEnumStateMachine<PlayerState>(animator, PlayerState.Idle);\n}\n3. Set state:
C#void Jump()\n{\n stateMachine.Value = PlayerState.Jumping;\n // Automatically sets Animator bools:\n // Idle = false\n // Running = false\n // Jumping = true\n // Falling = false\n}\nSetting stateMachine.Value automatically:
falsetrueThis ensures exclusive state control (only one state active).
"},{"location":"features/inspector/utility-components/#animator-setup","title":"Animator Setup","text":"Your Animator needs bool parameters matching enum names:
Text OnlyAnimator parameters:\n- Idle (bool)\n- Running (bool)\n- Jumping (bool)\n- Falling (bool)\n\nTransitions:\n- Any State \u2192 Idle: Idle == true\n- Any State \u2192 Running: Running == true\n- Any State \u2192 Jumping: Jumping == true\n- Any State \u2192 Falling: Falling == true\nAnimatorEnumStateMachine<T> is serializable for debugging in Inspector.
What it does: Singleton MonoBehaviour that provides a global coroutine host for non-MonoBehaviour classes.
Problem it solves: Coroutines require a MonoBehaviour to start. Static classes, plain C# objects, and ScriptableObjects can't start coroutines directly.
"},{"location":"features/inspector/utility-components/#when-to-use_9","title":"When to Use","text":"\u2705 Use for:
\u274c Don't use for:
using WallstopStudios.UnityHelpers.Utils;\n\n// From anywhere\nCoroutineHandler.Instance.StartCoroutine(MyCoroutine());\n\nIEnumerator MyCoroutine()\n{\n yield return new WaitForSeconds(1f);\n Debug.Log(\"Done!\");\n}\nCoroutineHandler persists across scene loads (DontDestroyOnLoad), so coroutines survive scene transitions.
Coroutine routine = CoroutineHandler.Instance.StartCoroutine(MyCoroutine());\n// ... later\nCoroutineHandler.Instance.StopCoroutine(routine);\nWhat it does: Simple component that tracks whether MonoBehaviour.Start() has been called.
Problem it solves: Sometimes you need to know if initialization (Start) has completed, especially in the editor or during complex initialization orders.
"},{"location":"features/inspector/utility-components/#when-to-use_10","title":"When to Use","text":"\u2705 Use for:
\u274c Don't use for:
using WallstopStudios.UnityHelpers.Utils;\n\n// Add to GameObject\nStartTracker tracker = gameObject.AddComponent<StartTracker>();\n\n// Later, check if Start has been called\nif (tracker.Started)\n{\n // Initialization complete\n}\nAutomatically syncs PolygonCollider2D shape to sprite's physics shape.
See: Editor Tools Guide - MatchColliderToSprite
"},{"location":"features/inspector/utility-components/#polygoncollider2doptimizer","title":"PolygonCollider2DOptimizer","text":"Reduces PolygonCollider2D point count using Douglas-Peucker simplification.
See: Editor Tools Guide - PolygonCollider2DOptimizer
"},{"location":"features/inspector/utility-components/#best-practices","title":"Best Practices","text":""},{"location":"features/inspector/utility-components/#general","title":"General","text":"These components solve the problem of creating complex, multi-layer sprite animations without pre-rendering every combination into massive sprite sheets.
"},{"location":"features/inspector/visual-components/#animatedspritelayer","title":"AnimatedSpriteLayer","text":"What it is: An immutable data structure (struct) that packages a sprite animation sequence with per-frame position offsets and layer-wide alpha transparency.
Why it exists: When building complex sprite animations (like a character with equipment, effects, or layered body parts), you need a standardized way to represent each layer with its timing, positioning, and transparency. This struct is the building block for the LayeredImage composition system.
Problem it solves:
\u2705 Use when:
LayeredImage compositions\u274c Don't use when:
Animator)using WallstopStudios.UnityHelpers.Visuals;\nusing UnityEngine;\n\n// Create a layer from sprite sequence\nSprite[] walkCycleFrames = LoadWalkCycleSprites(); // Must have Read/Write enabled!\n\n// Optional: per-frame offsets in world space (e.g., for bobbing motion)\nVector2[] walkBobOffsets = new[]\n{\n new Vector2(0, 0.1f), // Frame 0: slight up\n new Vector2(0, 0), // Frame 1: neutral\n new Vector2(0, 0.1f), // Frame 2: slight up\n new Vector2(0, 0) // Frame 3: neutral\n};\n\nAnimatedSpriteLayer bodyLayer = new AnimatedSpriteLayer(\n sprites: walkCycleFrames,\n worldSpaceOffsets: walkBobOffsets,\n alpha: 1f // Fully opaque\n);\n\n// Create equipment layer (same frame count, different sprites)\nSprite[] helmetFrames = LoadHelmetSprites();\nAnimatedSpriteLayer helmetLayer = new AnimatedSpriteLayer(\n sprites: helmetFrames,\n worldSpaceOffsets: null, // No offsets\n alpha: 0.9f // Slightly transparent\n);\n\n// Combine in LayeredImage (see below)\nIn editor code, you can create layers directly from AnimationClips:
C##if UNITY_EDITOR\nusing UnityEditor;\n\nAnimationClip walkClip = AssetDatabase.LoadAssetAtPath<AnimationClip>(\"Assets/Animations/Walk.anim\");\nAnimatedSpriteLayer layer = new AnimatedSpriteLayer(\n clip: walkClip,\n worldSpaceOffsets: null,\n alpha: 1f\n);\n#endif\nTexture Readability: All sprites must have Read/Write Enabled in their texture import settings. The constructor validates this and logs errors for non-readable textures.
To fix:
Frame Rate: Default frame rate is 12 fps (stored in AnimatedSpriteLayer.FrameRate constant). This matches classic sprite animation timing.
Offset Conversion: World-space offsets are automatically converted to pixel-space using sprite pixels-per-unit. This ensures offsets scale correctly with sprite resolution.
"},{"location":"features/inspector/visual-components/#layeredimage","title":"LayeredImage","text":"What it is: A UI Toolkit VisualElement that composites multiple AnimatedSpriteLayer instances into a single animated image with alpha blending, automatic cropping, and frame timing.
Why it exists: Creating character customization systems (body + equipment), visual effects (base + glow), or any multi-layer sprite animation traditionally requires pre-rendering every combination into massive sprite sheets. LayeredImage composes layers dynamically at runtime.
Problem it solves:
\u2705 Use when:
\u274c Don't use when:
Image or Animator)EnhancedImage for UGUI, though it doesn't support layering)using WallstopStudios.UnityHelpers.Visuals.UIToolkit;\nusing UnityEngine.UIElements;\n\n// Create layers (see AnimatedSpriteLayer section above)\nAnimatedSpriteLayer[] layers = new[]\n{\n bodyLayer, // Base character\n armorLayer, // Equipment layer 1\n helmetLayer, // Equipment layer 2\n glowLayer // Effect layer\n};\n\n// Create LayeredImage\nLayeredImage characterImage = new LayeredImage(\n inputSpriteLayers: layers,\n backgroundColor: null, // Transparent background (or use Color for solid background)\n fps: 12f, // Animation speed\n updatesSelf: true, // Automatically advances frames (uses Unity editor ticks or coroutines)\n pixelCutoff: 0.01f // Alpha threshold for cropping transparent pixels\n);\n\n// Add to UI Toolkit hierarchy\nrootVisualElement.Add(characterImage);\nIf you need precise control over frame advancement:
C#LayeredImage manualImage = new LayeredImage(\n inputSpriteLayers: layers,\n backgroundColor: null,\n fps: 12f,\n updatesSelf: false, // Disable automatic updates\n pixelCutoff: 0.01f\n);\n\n// In your update loop\nvoid Update()\n{\n manualImage.Update(force: false); // Advances frame based on elapsed time\n}\n\n// Or force immediate frame advance\nmanualImage.Update(force: true);\n// Set frames per second at runtime\ncharacterImage.Fps = 24f; // Speed up animation\ncharacterImage.Fps = 6f; // Slow down animation\nLayeredImage in Action
Character with dynamically composited layers animating at runtime
Swapping equipment layers at runtime without pre-rendered sprite sheets
"},{"location":"features/inspector/visual-components/#how-compositing-works","title":"How Compositing Works","text":"LayeredImage performs these steps each frame:
pixelCutoff)Performance optimization:
Controls how aggressive transparent pixel cropping is:
C#// More aggressive cropping (removes near-transparent pixels)\nlayeredImage.pixelCutoff = 0.05f;\n\n// Less aggressive (keeps more semi-transparent pixels)\nlayeredImage.pixelCutoff = 0.001f;\n\n// No cropping (includes fully transparent border)\nlayeredImage.pixelCutoff = 0f;\nHigher values = smaller final image, but may clip soft edges (glows, shadows).
"},{"location":"features/inspector/visual-components/#important-notes_1","title":"Important Notes","text":"Frame Synchronization: All layers must have the same number of frames. Mixing 4-frame and 8-frame animations will cause visual glitches.
Performance Considerations:
Editor vs Runtime:
updatesSelf settingWhat it is: An extended version of Unity's UI Image component with HDR color support and texture-based shape masking.
Why it exists: Unity's standard Image component doesn't support:
See full documentation: Editor Tools Guide - EnhancedImage
Visual Demo
HDR color values above 1.0 create bloom effects when post-processing is enabled
Quick example:
C#using WallstopStudios.UnityHelpers.Visuals.UGUI;\n\nEnhancedImage image = GetComponent<EnhancedImage>();\n\n// HDR color for bloom\nimage.HdrColor = new Color(2f, 0.5f, 0.1f, 1f); // RGB values > 1 for bloom\n\n// Shape mask\nimage.shapeMask = myMaskTexture; // Black areas are transparent\nSamples~ folder in the repositoryQ: Can I mix different frame counts in LayeredImage? A: No, all layers must have the same frame count. Pad shorter animations with duplicate frames if needed.
Q: Why are my layers not aligned correctly? A: Check that sprite pivots are set correctly (usually center). LayeredImage respects sprite pivot points.
Q: Can I change layers at runtime? A: Currently no, LayeredImage is immutable after construction. Create a new instance with updated layers.
Q: Performance impact vs pre-rendered sprites? A: Compositing costs ~1-3ms per image on modern hardware. Pre-rendered is faster but uses more memory/storage.
Q: Does this work with Unity's Animator? A: No, LayeredImage is independent. It's designed for UI Toolkit programmatic control.
Q: Can I export the composited result? A: Not directly, but you could capture the rendered texture using Texture2D.ReadPixels in a render texture setup.
Bring structured, color-coded logs to any Unity project without sprinkling Debug.Log everywhere. WallstopStudiosLogger adds extension methods (this.Log, this.LogWarn, this.LogError, this.LogDebug) that automatically capture component metadata, thread info, timestamps, and user-defined tags rendered by UnityLogTagFormatter.
UnityMainThreadDispatcher / UnityMainThreadGuard).time|GameObject[Component] when logging on the main thread and inserts |thread| only when background workers emit messages, keeping logs deterministic without extra noise.$\"{name:b,color=cyan}\") without string concatenation. Tags deduplicate automatically and can be stacked in any order.These helpers live in Runtime/Core/Extension/WallstopStudiosLogger.cs and Runtime/Core/Helper/Logging/UnityLogTagFormatter.cs. Tests at Tests/Runtime/Extensions/LoggingExtensionTests.cs demonstrate every supported scenario.
Logging \u2013 Tag Formatter package sample and open Samples~/Logging - Tag Formatter/Scenes/LoggingDemo.unity.LoggingDemoBootstrap (decorator registration) and LoggingDemoController (runtime toggles + this.Log* usage) to copy the patterns into your project.using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Extension;\n\npublic sealed class EnemyHUD : MonoBehaviour\n{\n private void Start()\n {\n string mode = Application.isEditor ? \"Test\" : \"Live\";\n int hp = 42;\n\n this.Log(\n $\"Player {\"Rogue-17\":b,color=orange} :: HP {hp:color=#FF4444} ({mode:italic})\"\n );\n }\n}\npretty: false if you only want the decorated text without the timestamp (or optional thread) prefix.this.LogWarn, this.LogError, or this.LogDebug for severity-specific output; all overloads accept Exception e to append stack traces.ENABLE_UBERLOGGING is defined automatically for DEBUG, DEVELOPMENT_BUILD, and UNITY_EDITOR. Define it manually (or DEBUG_LOGGING / WARN_LOGGING / ERROR_LOGGING) in Player Settings if you need the extensions in release builds.
:b, :bold, :! Wraps value in <b> Editor-only (uses Unity rich text) :i, :italic, :_ Wraps value in <i> Editor-only :json Serializes value via ToJson() Works in player builds :#color, :color=name, :color=#hex Wraps with <color=...> Named colors resolve to UnityEngine.Color constants :42, :size=42 Wraps with <size=42> Integers 1\u2013100 (or any positive int) $\"{stats:json,b,color=yellow}\" emits bold, colored JSON.:b has no effect.Register project-specific tags at startup (for example, in an InitializeOnLoad editor script or a runtime bootstrapper):
using WallstopStudios.UnityHelpers.Core.Extension;\nusing WallstopStudios.UnityHelpers.Core.Helper.Logging;\n\n[InitializeOnLoad]\ninternal static class LoggingBootstrap\n{\n static LoggingBootstrap()\n {\n UnityLogTagFormatter formatter = WallstopStudiosLogger.LogInstance;\n\n formatter.AddDecoration(\n predicate: tag => tag.StartsWith(\"stat:\", StringComparison.OrdinalIgnoreCase),\n format: (tag, value) =>\n {\n string label = tag.Substring(\"stat:\".Length);\n return $\"<color=#7AD7FF>[{label}]</color> {value}\";\n },\n tag: \"StatLabel\",\n priority: -10 // run before built-ins\n );\n }\n}\nKey APIs:
AddDecoration(string match, Func<object,string> format, string tag, int priority = 0, bool editorOnly = false, bool force = false)AddDecoration(Func<string,bool> predicate, Func<string,object,string> format, string tag, int priority = 0, bool editorOnly = false, bool force = false)RemoveDecoration(string tag, out Decoration removed) to swap or disable decorators at runtime.UnityLogTagFormatter.Separator (',') controls how stacked tags are parsed.Use negative priorities for \u201couter\u201d wrappers (run earlier) and higher numbers for final passes. Setting force: true replaces existing tags with the same name.
component.Log(FormattableString, Exception e = null, bool pretty = true) Sends an info log through the formatter. Guarded by ENABLE_UBERLOGGING/DEBUG_LOGGING. component.LogWarn(...), component.LogError(...), component.LogDebug(...) Severity-specific variants with the same signature. component.GenericToString() Serializes all public fields/properties into JSON (used by the formatter when you pass :json). component.EnableLogging() / component.DisableLogging() Per-object toggle. Disabled components are skipped without allocations. component.GlobalEnableLogging() / component.GlobalDisableLogging() / SetGlobalLoggingEnabled(bool) Global kill switch suitable for in-game consoles or dev toggles. WallstopStudiosLogger.IsGlobalLoggingEnabled() Query current state (useful for tooling UIs). Additional behavior:
UnityMainThreadDispatcher.TryDispatchToMainThread first. If unavailable, it falls back to UnityMainThreadGuard.TryPostToMainThread and, if that fails, emits an \u201coffline\u201d log with a [WallstopMainThreadLogger:*] prefix.timestamp|GameObject[Component]|message on the main thread, inserting |thread| only for worker threads). Pass pretty: false when emitting data the Unity console already decorates (for example, performance CSV dumps).Debug.Log*, preserving click-to-focus navigation even when logs originate from pooled helper classes.[RuntimeInitializeOnLoadMethod] to register project-wide tags. Avoid allocating per-frame delegates.$\"{health:json}\" keeps minimal formatting allocations compared to string.Format.pretty: false for exporters \u2014 When writing to files or parsing logs, disable prefixes to simplify downstream tooling.ENABLE_UBERLOGGING (or DEBUG_LOGGING / WARN_LOGGING / ERROR_LOGGING) and make sure log volume is acceptable (or wrap noisy calls in your own #defines).Tests/Runtime/Extensions/LoggingExtensionTests.cs covers every default tag and stacking scenario. Copy those patterns when adding new decorations to ensure behavior stays deterministic.UnityMainThreadDispatcher and UnityMainThreadGuard provide thread-safe access to Unity's main thread from background workers, ensuring callbacks execute correctly and preventing common threading errors.
UnityMainThreadDispatcher Dispatch work to the main thread dispatcher.RunOnMainThread(() => ...) UnityMainThreadGuard Assert code is on the main thread UnityMainThreadGuard.EnsureMainThread()"},{"location":"features/logging/unity-main-thread-dispatcher/#unitymainthreaddispatcher","title":"UnityMainThreadDispatcher","text":"The UnityMainThreadDispatcher is the package-wide bridge for marshaling callbacks from worker threads back onto Unity's main thread. The dispatcher is implemented as a RuntimeSingleton<UnityMainThreadDispatcher>, is marked [ExecuteAlways], and runs both in Edit Mode and Play Mode so background logging, importers, and build scripts can all enqueue work safely.
using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Helper;\n\npublic class BackgroundProcessor\n{\n public void ProcessOnWorkerThread()\n {\n // Queue work from any thread to execute on Unity's main thread\n UnityMainThreadDispatcher.Instance.RunOnMainThread(() =>\n {\n // This code executes on the main thread during the next Update\n Debug.Log(\"Safe to call Unity APIs here\");\n Object.FindObjectOfType<Player>().UpdateState();\n });\n }\n}\n// Queue action to run on main thread (logs warning if queue is full)\nUnityMainThreadDispatcher.Instance.RunOnMainThread(Action action);\n\n// Queue action silently (returns false if queue is full, no warning)\nbool queued = UnityMainThreadDispatcher.Instance.TryRunOnMainThread(Action action);\n\n// Check current queue depth\nint pending = UnityMainThreadDispatcher.Instance.PendingActionCount;\n\n// Configure queue limit (0 = unlimited)\nUnityMainThreadDispatcher.Instance.PendingActionLimit = 4096;\n// Async/await with Unity API access\npublic async Task<GameObject> LoadAssetAsync(string path)\n{\n GameObject asset = await LoadFromDiskAsync(path);\n\n // Marshal instantiation to main thread\n TaskCompletionSource<GameObject> tcs = new();\n UnityMainThreadDispatcher.Instance.RunOnMainThread(() =>\n {\n tcs.SetResult(Object.Instantiate(asset));\n });\n\n return await tcs.Task;\n}\n\n// Thread Pool work\nThreadPool.QueueUserWorkItem(_ =>\n{\n ComputedData data = ProcessHeavyComputation();\n\n UnityMainThreadDispatcher.Instance.RunOnMainThread(() =>\n {\n ApplyToScene(data); // Safe Unity API calls\n });\n});\n\n// Task continuation\nTask.Run(() => ComputeData())\n .ContinueWith(task =>\n {\n UnityMainThreadDispatcher.Instance.RunOnMainThread(() =>\n {\n DisplayResults(task.Result);\n });\n });\nThe UnityMainThreadGuard is a guard/assertion that throws an exception if called from a background thread. Use it to protect Unity API access points that must never be called off-thread.
\u26a0\ufe0f Important: EnsureMainThread() does NOT dispatch work to the main thread. It throws InvalidOperationException if called from a background thread. To dispatch work, use UnityMainThreadDispatcher.Instance.RunOnMainThread().
\ud83d\udce6 Internal API: UnityMainThreadGuard is an internal class, accessible only within the Unity Helpers assembly or via [InternalsVisibleTo]. For most use cases, prefer using UnityMainThreadDispatcher directly which is public.
using WallstopStudios.UnityHelpers.Core.Helper;\n\npublic class PlayerManager\n{\n private Player _cachedPlayer;\n\n public Player Instance\n {\n get\n {\n // Throws if accessed from background thread\n UnityMainThreadGuard.EnsureMainThread();\n return _cachedPlayer;\n }\n }\n\n public void RefreshUI()\n {\n // Optional context string for better error messages\n UnityMainThreadGuard.EnsureMainThread(\"Refreshing player UI\");\n // Safe to interact with Unity objects here\n }\n}\nProblem: Unity APIs must be called from the main thread, but bugs can allow background thread access that causes silent corruption or crashes.
Solution: UnityMainThreadGuard.EnsureMainThread() fails fast with a clear error message, catching threading bugs during development.
// Throws InvalidOperationException if not on main thread\nUnityMainThreadGuard.EnsureMainThread();\nUnityMainThreadGuard.EnsureMainThread(\"optional context\");\n\n// Check without throwing (internal API)\nbool isMainThread = UnityMainThreadGuard.IsMainThread;\n[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSplashScreen)] (EnsureDispatcherBootstrap) spins up the dispatcher before user assemblies receive their own RuntimeInitializeOnLoadMethod callbacks. This guarantees that worker threads can enqueue diagnostics as soon as your game loads.[InitializeOnLoadMethod] (EnsureDispatcherBootstrapInEditor) mirrors the same behavior for Edit Mode tools. The bootstrap politely skips when play mode is already running, so it does not duplicate the instance scene-side.UnityMainThreadGuard.EnsureMainThread(...) before touching Unity APIs, so the dispatcher is always created on the real main thread even when background code tries to force instantiation.With no configuration, the dispatcher therefore always exists, enforces the queue bound exposed via PendingActionLimit, and is hidden from the hierarchy during Edit Mode by HideFlags.HideInHierarchy | HideFlags.HideInInspector | HideFlags.NotEditable.
Occasionally (especially in tests) you want to control exactly when the dispatcher is created so that scenes unload cleanly and Unity does not warn about hidden objects surviving domain reloads. Use the internal switch:
C#UnityMainThreadDispatcher.SetAutoCreationEnabled(false);\n// ... destroy any dispatcher instance if you want a completely clean slate ...\nUnityMainThreadDispatcher.SetAutoCreationEnabled(true);\nUnityMainThreadDispatcher.Instance will recreate the singleton on the main thread (and Play Mode bootstrap will recreate it on the following domain reload).UnityMainThreadDispatcher.DestroyExistingDispatcher or the test helper) before turning the feature back on so that stale instances are removed from Resources.FindObjectsOfTypeAll.UnityMainThreadDispatcher.AutoCreationScope wraps the toggle/cleanup pattern above in an IDisposable so you cannot forget to restore the previous state:
using UnityMainThreadDispatcher.AutoCreationScope scope =\n UnityMainThreadDispatcher.AutoCreationScope.Disabled(\n destroyExistingInstanceOnEnter: true,\n destroyInstancesOnDispose: true,\n destroyImmediate: true // prefer true in tests, false in runtime code\n );\n\n// Auto-creation is disabled inside the scope; manually enable or create instances as needed.\nAutoCreationEnabled value, switches to the desired state, and optionally destroys any existing dispatcher instances.Two dedicated bootstraps live under Tests/*/TestUtils and keep dispatcher lifetimes predictable during automated suites:
Tests/Runtime/TestUtils/UnityMainThreadDispatcherTestBootstrap.cs)","text":"C#[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)]\nprivate static void DisableAutoCreation()\n{\n UnityMainThreadDispatcher.SetAutoCreationEnabled(false);\n UnityMainThreadDispatcherTestHelper.DestroyDispatcherIfExists(immediate: true);\n}\nDestroyImmediate'd so play-mode tests can opt into dispatcher usage explicitly.CommonTestBase.BaseSetUp).Tests/Editor/TestUtils/UnityMainThreadDispatcherEditorTestBootstrap.cs)","text":"C#[InitializeOnLoad]\ninternal static class UnityMainThreadDispatcherEditorTestBootstrap\n{\n static UnityMainThreadDispatcherEditorTestBootstrap()\n {\n UnityMainThreadDispatcher.SetAutoCreationEnabled(false);\n // DestroyImmediate the hidden dispatcher object, if any.\n }\n}\nThe runtime and editor CommonTestBase fixtures demonstrate the intended per-test lifecycle via UnityMainThreadDispatcher.AutoCreationScope:
[SetUp] it grabs UnityMainThreadDispatcher.CreateTestScope(destroyImmediate: true) which internally disables auto-creation, destroys stragglers, and then re-enables auto-creation so the test can access Instance normally.Downstream packages can copy the exact pattern:
[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)] that disables auto-creation and destroys lingering instances.[InitializeOnLoad] editor bootstrap that mirrors the same behavior for Edit Mode.using var scope = UnityMainThreadDispatcher.AutoCreationScope.Disabled(...) so cleanup always runs.Following this workflow keeps Unity from warning about hidden GameObjects during test teardown, prevents worker threads from instantiating the dispatcher off-thread, and documents exactly when auto-creation is in effect for your package.
"},{"location":"features/relational-components/relational-components/","title":"Relational Component Attributes","text":"Visual
Auto-wire components in your hierarchy without GetComponent boilerplate. These attributes make common relationships explicit, robust, and easy to maintain.
SiblingComponent \u2014 same GameObjectParentComponent \u2014 up the transform hierarchyChildComponent \u2014 down the transform hierarchy (breadth-first)Collection Type Support: Each attribute works with:
Transform)Collider2D[])List<Rigidbody2D>)HashSet<Renderer>)All attributes support optional assignment, filters (tag/name), depth limits, max results, and interface/base-type resolution.
Having issues? Jump to Troubleshooting: see Troubleshooting.
Related systems: For data\u2011driven gameplay effects (attributes, tags, cosmetics), see Effects System and the README section Effects, Attributes, and Tags.
Curious how these attributes stack up against manual GetComponent* loops? Check the Relational Component Performance Benchmarks for operations-per-second and allocation snapshots.
Before (The Old Way):
C#void Awake()\n{\n sprite = GetComponent<SpriteRenderer>();\n if (sprite == null) Debug.LogError(\"Missing SpriteRenderer!\");\n\n rigidbody = GetComponentInParent<Rigidbody2D>();\n if (rigidbody == null) Debug.LogError(\"Missing Rigidbody2D in parent!\");\n\n colliders = GetComponentsInChildren<Collider2D>();\n if (colliders.Length == 0) Debug.LogWarning(\"No colliders in children!\");\n\n // Repeat for every component...\n // 15-30 lines of boilerplate per script\n}\nAfter (Relational Components):
C#[SiblingComponent] private SpriteRenderer sprite;\n[ParentComponent] private Rigidbody2D rigidbody;\n[ChildComponent] private Collider2D[] colliders;\n\nvoid Awake() => this.AssignRelationalComponents();\n// That's it. 4 lines total, all wired automatically with validation.\nPick the right attribute
SiblingComponent.ParentComponent.ChildComponent.One\u2011minute setup
C#[SiblingComponent] private SpriteRenderer sprite;\n[ParentComponent(OnlyAncestors = true)] private Rigidbody2D rb;\n[ChildComponent(OnlyDescendants = true, MaxDepth = 1)] private Collider2D[] childColliders;\n\nvoid Awake() => this.AssignRelationalComponents();\nGetComponent and fragile manual wiringusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class Player : MonoBehaviour\n{\n // Same-GameObject\n [SiblingComponent] private SpriteRenderer sprite;\n\n // First matching ancestor (excluding self)\n [ParentComponent(OnlyAncestors = true)] private Rigidbody2D ancestorRb;\n\n // Immediate children only, collect many\n [ChildComponent(OnlyDescendants = true, MaxDepth = 1)]\n private Collider2D[] immediateChildColliders;\n\n private void Awake()\n {\n // Wires up all relational fields on this component\n this.AssignRelationalComponents();\n }\n}\nDecorate private (or public) fields on a MonoBehaviour with a relational attribute, then call one of:
this.AssignRelationalComponents() \u2014 assign all three categoriesthis.AssignSiblingComponents() \u2014 only siblingsthis.AssignParentComponents() \u2014 only parentsthis.AssignChildComponents() \u2014 only childrenAssignments happen at runtime (e.g., Awake/OnEnable), not at edit-time serialization.
ParentComponent (searches UP the hierarchy):\n\n Grandparent \u2190\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 (included unless OnlyAncestors = true)\n \u2191\n \u2502\n Parent \u2190\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 (always included)\n \u2191\n \u2502\n [YOU] \u2190\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 Component with [ParentComponent]\n \u2502\n Child\n \u2502\n Grandchild\n\n\nChildComponent (searches DOWN the hierarchy, breadth-first):\n\n Grandparent\n \u2502\n Parent\n \u2502\n [YOU] \u2190\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 Component with [ChildComponent]\n \u2193\n \u251c\u2500 Child 1 \u2190\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 (depth = 1)\n \u2502 \u251c\u2500 Grandchild 1 (depth = 2)\n \u2502 \u2514\u2500 Grandchild 2 (depth = 2)\n \u2502\n \u2514\u2500 Child 2 \u2190\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 (depth = 1)\n \u2514\u2500 Grandchild 3 (depth = 2)\n\n Breadth-first means all Children (depth 1) are checked\n before any Grandchildren (depth 2).\n\n\nSiblingComponent (searches same GameObject):\n\n Parent\n \u2502\n \u2514\u2500 [GameObject] \u2190\u2500\u2500\u2500\u2500\u2500\u2500 All components on this GameObject\n \u251c\u2500 [YOU] \u2190\u2500\u2500\u2500\u2500\u2500\u2500\u2500 Component with [SiblingComponent]\n \u251c\u2500 Component A\n \u251c\u2500 Component B\n \u2514\u2500 Component C\nOnlyAncestors / OnlyDescendants:
OnlyAncestors = true \u2192 Excludes self, searches only parents/grandparentsOnlyDescendants = true \u2192 Excludes self, searches only children/grandchildrenMaxDepth:
MaxDepth = 1 with OnlyDescendants = true \u2192 immediate children onlyMaxDepth = 2 \u2192 children + grandchildren (or parents + grandparents)\ud83d\udca1 Having Issues? Components not being assigned? Fields staying null? Jump to Troubleshooting for solutions to common problems.
"},{"location":"features/relational-components/relational-components/#attribute-reference","title":"Attribute Reference","text":""},{"location":"features/relational-components/relational-components/#siblingcomponent","title":"SiblingComponent","text":"GameObjectExamples:
C#[SiblingComponent] private Animator animator; // required by default\n[SiblingComponent(Optional = true)] private Rigidbody2D rb; // optional\n[SiblingComponent(TagFilter = \"Visual\", NameFilter = \"Sprite\")] private Component[] visuals;\n[SiblingComponent(MaxCount = 2)] private List<Collider2D> firstTwo; // List<T> supported\n[SiblingComponent] private HashSet<Renderer> allRenderers; // HashSet<T> supported\nPerformance note: Sibling lookups do not cache results between calls. In profiling we found these assignments typically run once per GameObject (e.g., during Awake), so the extra bookkeeping and invalidation cost of a cache outweighed the benefits. If you need updated references later, call AssignSiblingComponents again after the hierarchy changes.
OnlyAncestors, MaxDepthExamples:
C#// Immediate parent only\n[ParentComponent(OnlyAncestors = true, MaxDepth = 1)] private Transform directParent;\n\n// Up to 3 levels with a tag\n[ParentComponent(OnlyAncestors = true, MaxDepth = 3, TagFilter = \"Player\")] private Collider2D playerAncestor;\n\n// Interface/base-type resolution is supported by default\n[ParentComponent] private IHealth healthProvider;\nOnlyDescendants, MaxDepthExamples:
C#// Immediate children only\n[ChildComponent(OnlyDescendants = true, MaxDepth = 1)] private Transform[] immediateChildren;\n\n// First matching descendant with a tag\n[ChildComponent(OnlyDescendants = true, TagFilter = \"Weapon\")] private Collider2D weaponCollider;\n\n// Gather into a List (preserves insertion order)\n[ChildComponent(OnlyDescendants = true)] private List<MeshRenderer> childRenderers;\n\n// Gather into a HashSet (unique results, no duplicates) and limit count\n[ChildComponent(OnlyDescendants = true, MaxCount = 10)] private HashSet<Rigidbody2D> firstTenRigidbodies;\nPerformance note: When you avoid depth limits and interface filtering, child assignments run through a cached GetComponentsInChildren<T>() delegate to stay allocation-free. Turning on MaxDepth or interface searches still works, but the assigner reverts to the breadth-first traversal to honour those constraints.
Optional (default: false)false, logs a descriptive error when no match is foundIf true, suppresses the error (field remains null/empty)
IncludeInactive (default: true)
true, includes disabled components and inactive GameObjectsIf false, only assigns enabled components on active-in-hierarchy objects
SkipIfAssigned (default: false)
If true, preserves existing non-null value (single) or non-empty collection
MaxCount (default: 0 = unlimited)
Applies to arrays, lists, and hash sets; ignored for single fields
TagFilter
Exact tag match using CompareTag
NameFilter
Case-sensitive substring match on the GameObject name
AllowInterfaces (default: true)
true, can assign by interface or base type; set false to restrict to concrete typesUse Arrays (T[]) when:
Use Lists (List<T>) when:
[] operatorUse HashSets (HashSet<T>) when:
Contains())// Arrays: Fixed size, minimal overhead\n[ChildComponent] private Collider2D[] colliders;\n\n// Lists: Dynamic, ordered, index-based access\n[ChildComponent] private List<Renderer> renderers;\n\n// HashSets: Unique, fast lookups, unordered\n[ChildComponent] private HashSet<AudioSource> audioSources;\n[ParentComponent(OnlyAncestors = true, MaxDepth = 2)] private Canvas canvas;\n[ChildComponent(OnlyDescendants = true, NameFilter = \"Button\")] private Button[] buttons;\n[ChildComponent(OnlyDescendants = true, TagFilter = \"Sensor\")] private Collider[] sensors;\npublic interface IInputProvider { Vector2 Move { get; } }\n[ParentComponent] private IInputProvider input; // PlayerInput, AIInput, etc.\nAwake() or OnEnable() so references exist earlyAssignSibling/Parent/Child) when you only use one categoryMaxDepth to cap traversal cost in deep treesMaxCount to reduce allocations when you only need a subsetOptional = true to avoid noiseRelational components build high\u2011performance reflection helpers on first use. To eliminate this lazy cost and avoid first\u2011frame stalls on large projects or IL2CPP builds, explicitly pre\u2011initialize caches at startup:
C#// Call during bootstrap/loading\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\nvoid Start()\n{\n RelationalComponentInitializer.Initialize();\n}\nNotes:
RelationalComponentInitializer.Initialize(new[]{ typeof(MyComponent) });Stop choosing between DI and clean hierarchy references - Unity Helpers provides seamless integrations with Zenject/Extenject, VContainer, and Reflex that automatically wire up your relational component fields right after dependency injection completes.
"},{"location":"features/relational-components/relational-components/#the-di-pain-point","title":"The DI Pain Point","text":"Without these integrations, you're stuck writing Awake() methods full of GetComponent boilerplate even when using a DI framework:
public class Enemy : MonoBehaviour\n{\n [Inject] private IHealthSystem _health; // \u2705 DI handles this\n\n private Animator _animator; // \u274c Still manual boilerplate\n private Rigidbody2D _rigidbody; // \u274c Still manual boilerplate\n\n void Awake()\n {\n _animator = GetComponent<Animator>();\n _rigidbody = GetComponent<Rigidbody2D>();\n // ... 15 more lines of GetComponent hell\n }\n}\nWith the DI integrations, everything just works:
C#public class Enemy : MonoBehaviour\n{\n [Inject] private IHealthSystem _health; // \u2705 DI injection\n [SiblingComponent] private Animator _animator; // \u2705 Relational auto-wiring\n [SiblingComponent] private Rigidbody2D _rigidbody; // \u2705 Relational auto-wiring\n\n // No Awake() needed! Both DI and hierarchy references wired automatically\n}\nAwake() method needed, no manual GetComponent calls, no validation codeUnity Helpers automatically detects these packages via UPM:
com.extenject.zenject, com.modesttree.zenject, com.svermeulen.extenjectjp.cysharp.vcontainer, jp.hadashikick.vcontainercom.gustavopsantos.reflex\ud83d\udca1 UPM packages work out-of-the-box - No scripting defines needed!
"},{"location":"features/relational-components/relational-components/#manual-or-source-imports-non-upm","title":"Manual or Source Imports (Non-UPM)","text":"If you import Zenject/VContainer/Reflex as source code, .unitypackage, or raw DLLs (not via UPM), you need to manually add scripting defines:
Project Settings > Player > Other Settings > Scripting Define SymbolsZENJECT_PRESENT - When using Zenject/ExtenjectVCONTAINER_PRESENT - When using VContainerREFLEX_PRESENT - When using ReflexRuntime/Integrations/* will activate automaticallybuilder.RegisterRelationalComponents(\n new RelationalSceneAssignmentOptions(includeInactive: true, useSinglePassScan: true),\n enableAdditiveSceneListener: true\n);\n_resolver.InstantiateComponentWithRelations(componentPrefab, parent)_resolver.InstantiateGameObjectWithRelations(rootPrefab, parent, includeInactiveChildren: true)_resolver.AssignRelationalHierarchy(existingRoot, includeInactiveChildren: true)RelationalObjectPools.CreatePoolWithRelations(...) + pool.GetWithRelations(resolver)
Full walkthrough: See Samples~/DI - VContainer folder in the repository
RelationalComponentsInstaller to your SceneContext.Toggles cover include-inactive scanning, single-pass strategy, and additive-scene listening.
Runtime helpers
_container.InstantiateComponentWithRelations(componentPrefab, parent)_container.InstantiateGameObjectWithRelations(rootPrefab, parent, includeInactiveChildren: true)_container.AssignRelationalHierarchy(existingRoot, includeInactiveChildren: true)Subclass RelationalMemoryPool<T> to hydrate pooled items on spawn.
Full walkthrough: See Samples~/DI - Zenject folder in the repository
SceneScope in each scene. Add RelationalComponentsInstaller to the same GameObject (or a child) to bind the relational assigner, run the initial scene scan, and optionally register the additive-scene listener.Toggles mirror the runtime helpers: include inactive objects, choose the scan strategy, and enable additive listening.
Runtime helpers
_container.InjectWithRelations(existingComponent) to inject DI fields and hydrate relational attributes on existing objects._container.InstantiateComponentWithRelations(componentPrefab, parent) for component prefabs._container.InstantiateGameObjectWithRelations(rootPrefab, parent, includeInactiveChildren: true) for full hierarchies._container.AssignRelationalHierarchy(existingRoot, includeInactiveChildren: true) to hydrate arbitrary hierarchies after manual instantiation.
Full walkthrough: See Samples~/DI - Reflex folder in the repository
Reflex shares the same fallback behaviour: if the assigner is not bound, the helpers call AssignRelationalComponents() directly so you can adopt incrementally.
Notes
component.AssignRelationalComponents() call path if the DI container does not expose the assigner binding, so you can adopt them incrementally without breaking existing behaviour.Expected in Edit Mode. These attributes are assigned at runtime only and are not serialized. They are checked at runtime and log errors if they fail to find a match.
Nothing assigned at runtime
AssignRelationalComponents() or the specific Assign*Components() in Awake() or OnEnable().TagFilter must match an existing tag; NameFilter is case-sensitive.OnlyAncestors/OnlyDescendants may exclude self; MaxDepth may be too small.For interface/base type fields, confirm AllowInterfaces = true (default) or use a concrete type.
Inactive or disabled components unexpectedly included
These are included by default. Set IncludeInactive = false to restrict to enabled components on active GameObjects.
Too many results or large allocations
Cap with MaxCount and/or MaxDepth. Prefer List<T> or HashSet<T> when you plan to mutate the collection after assignment.
Child search doesn\u2019t find the nearest match you expect
Children are traversed breadth-first. If you want the nearest by hierarchy level, this is correct; if you need a custom order, gather a collection and sort manually.
I only need one category (e.g., parents)
AssignParentComponents / AssignChildComponents / AssignSiblingComponents) instead of the all-in-one method for clarity and potentially less work.Q: Does this run in Edit Mode or serialize values?
Q: Are interfaces supported?
AllowInterfaces = true (default). Set it to false to restrict to concrete types.Q: What about performance?
MaxDepth, TagFilter, NameFilter, and MaxCount to limit work. Sibling lookups are O(1) when no filters are applied.For quick examples in context, see the README\u2019s \u201cAuto Component Discovery\u201d section. For API docs, hover the attributes in your IDE for XML summaries and examples.
"},{"location":"features/relational-components/relational-components/#di-integrations-testing-and-edge-cases","title":"DI Integrations: Testing and Edge Cases","text":"Beginner-friendly overview
ZENJECT_PRESENT, VCONTAINER_PRESENT). With UPM, these are added via asmdef versionDefines. Without UPM (manual import), add them in Project Settings \u2192 Player \u2192 Scripting Define Symbols.IRelationalComponentAssigner) and provide a scene initializer/entry point to hydrate relational fields once the container is ready.VContainer (1.16.x)
builder.RegisterRelationalComponents() in LifetimeScope.Configure. The entry point runs automatically after the container builds. You can enable an additive-scene listener and customize scan options:using VContainer;\nusing VContainer.Unity;\nusing WallstopStudios.UnityHelpers.Integrations.VContainer;\n\nprotected override void Configure(IContainerBuilder builder)\n{\n // Single-pass scan + additive scene listener\n var options = new RelationalSceneAssignmentOptions(includeInactive: true, useSinglePassScan: true);\n builder.RegisterRelationalComponents(options, enableAdditiveSceneListener: true);\n}\nInitialize() yourself, and register your AttributeMetadataCache instance so the assigner uses it:var cache = ScriptableObject.CreateInstance<AttributeMetadataCache>();\n// populate cache._relationalTypeMetadata with your test component types\ncache.ForceRebuildForTests(); // rebuild lookups so the initializer can discover your types\nvar builder = new ContainerBuilder();\nbuilder.RegisterInstance(cache).AsSelf();\nbuilder.Register<RelationalComponentAssigner>(Lifetime.Singleton)\n .As<IRelationalComponentAssigner>()\n .AsSelf();\nvar resolver = builder.Build();\nvar entry = new RelationalComponentEntryPoint(\n resolver.Resolve<IRelationalComponentAssigner>(),\n cache,\n RelationalSceneAssignmentOptions.Default\n);\nentry.Initialize();\nresolver.InjectWithRelations(component) to inject + assign in one call, or resolver.Inject(component) then resolver.AssignRelationalComponents(component).Prefabs & GameObjects: resolver.InstantiateComponentWithRelations(prefab, parent) or resolver.InstantiateGameObjectWithRelations(prefab, parent); to inject existing hierarchies use resolver.InjectGameObjectWithRelations(root).
EditMode reliability: In EditMode tests, prefer [UnityTest] and yield return null after creating objects and after initializing the entry point so Unity has a frame to register new objects before FindObjectsOfType runs and to allow assignments to complete.
SceneManager.CreateScene, set it active, and move your test hierarchy into it before calling Initialize().RelationalSceneAssignmentOptions(includeInactive: bool).Zenject/Extenject
RelationalComponentsInstaller to your SceneContext. It binds IRelationalComponentAssigner and runs RelationalComponentSceneInitializer once the container is ready. The installer exposes toggles to assign on initialize and to listen for additive scenes.AttributeMetadataCache instance and construct the assigner with that cache. Then resolve IInitializable and call Initialize().[UnityTest] with a yield return null after creating objects and after calling Initialize() to allow Unity to register objects and complete assignments.container.InstantiateComponentWithRelations(...), container.InstantiateGameObjectWithRelations(...), or container.InjectGameObjectWithRelations(root); to inject + assign a single instance: container.InjectWithRelations(component).RelationalMemoryPool<T> (or <TParam, T>) to assign relational fields in OnSpawned automatically.RelationalObjectPools.CreatePoolWithRelations(...) and rent via pool.GetWithRelations(resolver) to inject + assign.Common pitfalls and how to avoid them
LifetimeScope. Construct the entry point manually as shown above.versionDefines; manual imports require adding them in Player Settings.AttributeMetadataCache has the relational metadata for your test component types and that the DI container uses the same cache instance (register it and prefer constructors that accept the cache).Core Guides:
Related Features:
DI Integration Samples:
Samples~/DI - VContainer folder in the repositorySamples~/DI - Zenject folder in the repositorySamples~/DI - Reflex folder in the repositoryNeed help? Open an issue | Troubleshooting
"},{"location":"features/serialization/serialization-types/","title":"Serialization Types","text":"Unity-friendly wrappers for complex data.
Unity Helpers provides serializable wrappers for types that Unity can't serialize natively: GUIDs, dictionaries, sets, type references, and nullable values. All types include custom property drawers for a seamless inspector experience and support JSON/Protobuf serialization.
"},{"location":"features/serialization/serialization-types/#table-of-contents","title":"Table of Contents","text":"Immutable version-4 GUID wrapper using two longs for efficient Unity serialization.
"},{"location":"features/serialization/serialization-types/#why-wguid","title":"Why WGuid?","text":"System.Guid directlyWGuid stores as two long fields (_low and _high) for fast Unity serializationPerformance:
using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.DataStructure.Adapters;\n\npublic class Entity : MonoBehaviour\n{\n public WGuid entityId = WGuid.NewGuid();\n}\nVisual Reference
"},{"location":"features/serialization/serialization-types/#creating-guids","title":"Creating GUIDs","text":"C#// Generate new GUID\nWGuid id1 = WGuid.NewGuid();\n\n// From System.Guid\nSystem.Guid sysGuid = System.Guid.NewGuid();\nWGuid id2 = (WGuid)sysGuid;\n\n// Parse from string\nWGuid id3 = WGuid.Parse(\"12345678-1234-1234-1234-123456789abc\");\n\n// Try parse (safe)\nif (WGuid.TryParse(\"...\", out WGuid id4))\n{\n Debug.Log($\"Parsed: {id4}\");\n}\n\n// Empty GUID\nWGuid empty = WGuid.EmptyGuid;\nCustom Drawer:
// WGuid <-> System.Guid\nWGuid wguid = WGuid.NewGuid();\nSystem.Guid sysGuid = wguid.ToGuid();\nWGuid back = (WGuid)sysGuid;\n\n// ToString() formats\nstring standard = wguid.ToString(); // \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"\nstring formatted = wguid.ToString(\"N\"); // Without hyphens\nWGuid id1 = WGuid.NewGuid();\nWGuid id2 = id1;\n\n// Implements IEquatable<WGuid>\nbool equal = id1.Equals(id2); // true\nbool opEqual = id1 == id2; // true\n\n// Implements IComparable<WGuid>\nint comparison = id1.CompareTo(id2); // 0\nlong fieldslong fieldsusing ProtoBuf;\n\n[ProtoContract]\npublic class SaveData\n{\n [ProtoMember(1)] public WGuid playerId;\n [ProtoMember(2)] public WGuid sessionId;\n}\nUnity-friendly dictionary with synchronized key/value arrays and custom drawer.
"},{"location":"features/serialization/serialization-types/#why-serializabledictionary","title":"Why SerializableDictionary?","text":"Dictionary<TKey, TValue>SerializableDictionary<TKey, TValue> maintains synchronized arrays for Unity serialization and a runtime dictionary for fast lookupsusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.DataStructure.Adapters;\n\npublic class PrefabRegistry : MonoBehaviour\n{\n public GameObject enemyPrefab;\n public GameObject playerPrefab;\n\n public SerializableDictionary<string, GameObject> prefabs;\n\n private void Start()\n {\n // Access entries\n if (prefabs.TryGetValue(\"Enemy\", out GameObject prefab))\n {\n Instantiate(prefab);\n }\n\n // Count\n Debug.Log($\"Prefab count: {prefabs.Count}\");\n\n // Iteration\n foreach (var kvp in prefabs)\n {\n Debug.Log($\"{kvp.Key}: {kvp.Value}\");\n }\n\n /*\n Add entries (or overwrite)\n WARNING: This is just for demo purposes! SerializableDictionary is meant for editor-mode persistence.\n Nothing stops you from changing this at runtime, but it will be lost on next playthrough.\n */\n prefabs[\"Player\"] = playerPrefab;\n prefabs[\"Enemy\"] = enemyPrefab;\n }\n}\nVisual Reference
Dictionary inspector showing key-value pairs with pagination and inline editing
Custom Drawer:
// Implements IDictionary<TKey, TValue> and IReadOnlyDictionary<TKey, TValue>\nSerializableDictionary<int, string> dict = new();\n\n// Add\ndict.Add(1, \"One\");\ndict[2] = \"Two\";\n\n// Read\nstring value = dict[1];\nbool exists = dict.TryGetValue(2, out string val);\nbool contains = dict.ContainsKey(1);\n\n// Update\ndict[1] = \"First\";\n\n// Remove\ndict.Remove(1);\ndict.Clear();\n\n// Iteration\nforeach (KeyValuePair<int, string> kvp in dict)\n{\n Debug.Log($\"{kvp.Key} = {kvp.Value}\");\n}\n\n// Keys/Values collections\nICollection<int> keys = dict.Keys;\nICollection<string> values = dict.Values;\n// Sorted dictionary (maintains key order)\npublic SerializableSortedDictionary<int, string> sortedDict;\nNote: SerializableSortedDictionary uses SortedDictionary<TKey, TValue> internally for ordered keys.
_keys and _values arrays// JSON example\n{\n \"prefabs\": {\n \"Enemy\": { \"instanceId\": 12345 },\n \"Player\": { \"instanceId\": 67890 }\n }\n}\nUnity-friendly set collections with duplicate detection and custom drawers.
"},{"location":"features/serialization/serialization-types/#why-serializable-sets","title":"Why Serializable Sets?","text":"HashSet<T> or SortedSet<T>SerializableHashSet<T> and SerializableSortedSet<T> maintain a serialized array and runtime set for fast lookupsusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.DataStructure.Adapters;\n\npublic class UniqueItemTracker : MonoBehaviour\n{\n public SerializableHashSet<string> collectedItems;\n\n private void Start()\n {\n foreach (var item in collectedItems)\n {\n Debug.Log($\"Found item: {item}\");\n }\n }\n}\nVisual Reference
Set inspector with add/remove controls, duplicate highlighting, and pagination
"},{"location":"features/serialization/serialization-types/#inspector-features_2","title":"Inspector Features","text":"Custom Drawer:
Visual Reference
Visual feedback for duplicate entries (yellow shake) and null values (red background)
"},{"location":"features/serialization/serialization-types/#set-operations","title":"Set Operations","text":"C#// Implements ISet<T> and IReadOnlyCollection<T>\nSerializableHashSet<int> set = new();\n\n// Add (returns true if new)\nbool added = set.Add(42);\n\n// Read\nbool contains = set.Contains(42);\nint count = set.Count;\n\n// Remove\nbool removed = set.Remove(42);\nset.Clear();\n\n// Set operations\nHashSet<int> other = new HashSet<int> { 1, 2, 3 };\nset.UnionWith(other); // Add all from other\nset.IntersectWith(other); // Keep only common elements\nset.ExceptWith(other); // Remove elements in other\nbool overlaps = set.Overlaps(other);\n\n// Iteration\nforeach (int item in set)\n{\n Debug.Log(item);\n}\nExpandable \"New Entry\" controls let you configure the exact value that will be inserted, which is especially helpful for complex structs, managed references, or ScriptableObjects. The foldout supports the same field variety as the inline list and respects your duplicate/null validation. Animation for the New Entry foldout is governed by the Serializable Set Foldouts settings; adjust tweening and speed independently for SerializableHashSet<T> and SerializableSortedSet<T>.
By default, SerializableSet inspectors start collapsed until you open them. This baseline comes from Project Settings \u25b8 Wallstop Studios \u25b8 Unity Helpers via the Serializable Set Start Collapsed toggle (and the equivalent Serializable Dictionary Start Collapsed toggle for dictionaries). You can override the default per-field with [WSerializableCollectionFoldout]:
using WallstopStudios.UnityHelpers.Core.Attributes;\n\n[WSerializableCollectionFoldout(WSerializableCollectionFoldoutBehavior.StartExpanded)]\npublic SerializableHashSet<string> unlockedBadges = new();\n[WSerializableCollectionFoldout] can request expanded or collapsed behavior for specific collections.SerializedProperty.isExpanded (scripts, custom inspectors, or tests) take ultimate precedence. The drawer now respects those manual decisions, so opting-in via code no longer gets undone by the attribute or the global default.The attribute applies to both SerializableHashSet<T>/SerializableSortedSet<T> and the dictionary equivalents, making it straightforward to mix project-wide defaults with per-field intentions.
using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\nusing WallstopStudios.UnityHelpers.Core.DataStructure.Adapters;\n\npublic class ThresholdLogger : MonoBehaviour\n{\n public SerializableSortedSet<int> scoreThresholds = new();\n\n [WButton]\n private string LogThresholds()\n {\n foreach (int threshold in scoreThresholds)\n {\n Debug.Log(threshold);\n }\n return $\"Logged {scoreThresholds.Count} thresholds\";\n }\n}\n_items array// JSON example\n{\n \"collectedItems\": [\"item_001\", \"item_042\", \"item_137\"]\n}\nUnity-friendly type reference that survives refactoring and namespace changes.
C#using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.DataStructure.Adapters;\n\npublic class SerializableTypeExample : MonoBehaviour\n{\n public SerializableType type;\n}\nVisual Reference
Type selection with searchable dropdown, namespace filtering, and validation
"},{"location":"features/serialization/serialization-types/#why-serializabletype","title":"Why SerializableType?","text":"System.Type, and type names break when refactoringSerializableType stores assembly-qualified names with fallback resolution on rename/namespace changesusing System;\nusing System.Collections.Generic;\nusing System.Linq;\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\nusing WallstopStudios.UnityHelpers.Core.DataStructure.Adapters;\nusing WallstopStudios.UnityHelpers.Core.Helper;\n\npublic class BehaviorSpawner : MonoBehaviour\n{\n [WValueDropDown(typeof(BehaviorSpawner), nameof(GetAllMonoBehaviourNames))]\n public SerializableType behaviorType;\n\n private void SpawnBehavior()\n {\n if (behaviorType.IsEmpty)\n {\n Debug.LogWarning(\"No behavior type assigned!\");\n return;\n }\n\n Type type = behaviorType.Value;\n if (type != null)\n {\n GameObject go = new GameObject(type.Name);\n go.AddComponent(type);\n }\n }\n\n private static IEnumerable<Type> GetAllMonoBehaviourNames()\n {\n return ReflectionHelpers\n .GetAllLoadedTypes()\n .Where(type => typeof(MonoBehaviour).IsAssignableFrom(type) && !type.IsAbstract);\n }\n}\nCustom Drawer (Two-Line):
// Create\nSerializableType typeRef = new SerializableType(typeof(PlayerController));\n\n// Resolve\nType resolvedType = typeRef.Value;\nif (resolvedType != null)\n{\n object instance = Activator.CreateInstance(resolvedType);\n}\n\n// Check\nbool isEmpty = typeRef.IsEmpty;\nstring displayName = typeRef.DisplayName; // User-friendly name\n\n// Equality\nbool equal = typeRef.Equals(new SerializableType(typeof(PlayerController)));\nScenario: You rename PlayerController to PlayerBehavior or move it to a new namespace.
How it works:
Namespace.PlayerController, Assembly-CSharp)// JSON example\n{\n \"behaviorType\": \"MyNamespace.PlayerController, Assembly-CSharp\"\n}\nUnity-friendly nullable value type wrapper.
"},{"location":"features/serialization/serialization-types/#why-serializablenullable","title":"Why SerializableNullable?","text":"Nullable<T> (e.g., int?, float?)SerializableNullable<T> wraps any value type with HasValue and Value propertiesusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.DataStructure.Adapters;\n\npublic class BonusConfig : MonoBehaviour\n{\n public SerializableNullable<float> criticalHitMultiplier;\n\n private float GetDamage(float baseDamage, bool isCritical)\n {\n if (isCritical && criticalHitMultiplier.HasValue)\n {\n return baseDamage * criticalHitMultiplier.Value;\n }\n return baseDamage;\n }\n}\nCustom Drawer:
HasValue stateHasValue == true)// Create with value\nSerializableNullable<int> nullableInt = new SerializableNullable<int>(42);\n\n// Create without value (null)\nSerializableNullable<int> nullInt = new SerializableNullable<int>();\n\n// Check\nif (nullableInt.HasValue)\n{\n int value = nullableInt.Value;\n Debug.Log($\"Value: {value}\");\n}\n\n// Implicit conversion from T\nSerializableNullable<float> nullableFloat = 3.14f;\n\n// Conversion to Nullable<T>\nint? systemNullable = nullableInt.HasValue ? nullableInt.Value : null;\nOptional Configuration:
C#public SerializableNullable<float> overrideSpeed; // null = use default\nConditional Bonuses:
C#public SerializableNullable<int> bonusGold; // null = no bonus\nDynamic Properties:
C#public SerializableNullable<Color> customColor; // null = use preset\n_hasValue bool and _value T fields// JSON example (has value)\n{\n \"criticalHitMultiplier\": 2.5\n}\n\n// JSON example (null)\n{\n \"criticalHitMultiplier\": null\n}\n// \u2705 GOOD: WGuid for entity IDs\npublic WGuid entityId = WGuid.NewGuid();\n\n// \u2705 GOOD: SerializableDictionary for key/value mappings\npublic SerializableDictionary<string, GameObject> prefabRegistry;\n\n// \u2705 GOOD: SerializableHashSet for unique collections\npublic SerializableHashSet<string> uniqueItemIds;\n\n// \u2705 GOOD: SerializableSortedSet for ordered unique values\npublic SerializableSortedSet<int> scoreThresholds;\n\n// \u2705 GOOD: SerializableType for type references\npublic SerializableType behaviorType;\n\n// \u2705 GOOD: SerializableNullable for optional values\npublic SerializableNullable<float> overrideSpeed;\n\n// \u274c BAD: String-based GUID\npublic string entityId = System.Guid.NewGuid().ToString(); // Use WGuid!\n\n// \u274c BAD: Parallel arrays instead of dictionary\npublic string[] keys;\npublic GameObject[] values; // Use SerializableDictionary!\n\n// \u274c BAD: List with manual duplicate checking\npublic List<string> uniqueItems; // Use SerializableHashSet!\n// \u2705 GOOD: Initialize in field declaration\npublic SerializableDictionary<string, int> scores = new();\npublic SerializableHashSet<string> tags = new();\n\n// \u274c BAD: Null collections (NullReferenceException!)\npublic SerializableDictionary<string, int> scores; // null!\n\nprivate void Start()\n{\n scores.Add(\"player\", 100); // Crash!\n}\n// \u2705 GOOD: SortedSet for ordered priorities\npublic SerializableSortedSet<int> unlockLevels;\n\n// \u2705 GOOD: SortedDictionary for ordered display\npublic SerializableSortedDictionary<string, string> alphabeticalNames;\n\n// \u274c BAD: HashSet for ordered data (no guaranteed order!)\npublic SerializableHashSet<int> unlockLevels; // Order is random!\n// \u2705 GOOD: Generate once, then immutable\npublic WGuid entityId = WGuid.NewGuid();\n\n// \u2705 GOOD: Generate in Awake if needed\nprivate void Awake()\n{\n if (entityId == WGuid.EmptyGuid)\n {\n entityId = WGuid.NewGuid();\n }\n}\n\n// \u274c BAD: Regenerating on every access\npublic WGuid EntityId => WGuid.NewGuid(); // New GUID every time!\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.DataStructure.Adapters;\n\n[System.Serializable]\npublic class ItemData\n{\n public string name;\n public Sprite icon;\n public int value;\n}\n\npublic class ItemDatabase : MonoBehaviour\n{\n public SerializableDictionary<string, ItemData> items;\n\n public bool TryGetItem(string itemId, out ItemData data)\n {\n return items.TryGetValue(itemId, out data);\n }\n\n public void AddItem(string itemId, ItemData data)\n {\n items[itemId] = data;\n }\n}\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.DataStructure.Adapters;\n\npublic class PlayerProfile : MonoBehaviour\n{\n public WGuid playerId = WGuid.NewGuid();\n public SerializableHashSet<string> unlockedAchievements;\n public SerializableSortedSet<int> highScores;\n\n public void UnlockAchievement(string achievementId)\n {\n if (unlockedAchievements.Add(achievementId))\n {\n Debug.Log($\"Unlocked: {achievementId}\");\n // Trigger UI notification, etc.\n }\n }\n\n public void RecordScore(int score)\n {\n highScores.Add(score);\n\n // Keep only top 10\n while (highScores.Count > 10)\n {\n highScores.Remove(highScores.Min);\n }\n }\n}\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.DataStructure.Adapters;\nusing System;\n\npublic class BehaviorFactory : MonoBehaviour\n{\n [StringInList(typeof(TypeHelper), nameof(TypeHelper.GetAllMonoBehaviours))]\n public SerializableType defaultBehavior;\n\n public SerializableDictionary<string, SerializableType> namedBehaviors;\n\n public GameObject SpawnWithBehavior(string behaviorName = null)\n {\n SerializableType typeToSpawn = defaultBehavior;\n\n if (!string.IsNullOrEmpty(behaviorName) &&\n namedBehaviors.TryGetValue(behaviorName, out SerializableType namedType))\n {\n typeToSpawn = namedType;\n }\n\n if (typeToSpawn.IsEmpty)\n {\n Debug.LogWarning(\"No behavior type specified!\");\n return null;\n }\n\n Type type = typeToSpawn.Value;\n if (type == null || !typeof(MonoBehaviour).IsAssignableFrom(type))\n {\n Debug.LogError($\"Invalid behavior type: {typeToSpawn.DisplayName}\");\n return null;\n }\n\n GameObject go = new GameObject(type.Name);\n go.AddComponent(type);\n return go;\n }\n}\n\npublic static class TypeHelper\n{\n public static IEnumerable<Type> GetAllMonoBehaviours()\n {\n return AppDomain.CurrentDomain.GetAssemblies()\n .SelectMany(a => a.GetTypes())\n .Where(t => typeof(MonoBehaviour).IsAssignableFrom(t) && !t.IsAbstract);\n }\n}\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.DataStructure.Adapters;\n\npublic class CharacterConfig : MonoBehaviour\n{\n public float baseSpeed = 5f;\n public SerializableNullable<float> speedOverride; // null = use baseSpeed\n\n public Color defaultColor = Color.white;\n public SerializableNullable<Color> colorOverride; // null = use defaultColor\n\n private void Start()\n {\n float actualSpeed = speedOverride.HasValue ? speedOverride.Value : baseSpeed;\n Color actualColor = colorOverride.HasValue ? colorOverride.Value : defaultColor;\n\n Debug.Log($\"Speed: {actualSpeed}, Color: {actualColor}\");\n }\n}\nNext Steps:
WGuidSerializableDictionary instead of parallel arraysSerializableHashSetSerializableTypeSerializableNullableVisuals
This package provides fast, compact serialization for save systems, configuration, and networking with a unified API.
All formats are exposed via WallstopStudios.UnityHelpers.Core.Serialization.Serializer and selected with SerializationType.
Human-readable; ideal for settings, debug, modding, and Git diffs.
\u2b50 Killer Feature: Schema Evolution \u2014 Players can load saves from older game versions without breaking! Add new fields, remove old ones, rename types\u2014all while maintaining compatibility.
Only for legacy or trusted, same-version, local data. Avoid for long-term persistence or untrusted input.
Use this decision flowchart to pick the right serialization format:
Text OnlySTART: What are you serializing?\n \u2502\n \u251c\u2500 Game settings / Config files\n \u2502 \u2502\n \u2502 \u251c\u2500 Need human-readable / Git-friendly?\n \u2502 \u2502 \u2192 JSON (Normal or Pretty) \u2713\n \u2502 \u2502\n \u2502 \u2514\u2500 Performance critical (large files)?\n \u2502 \u2192 JSON (Fast or FastPOCO) \u2713\n \u2502\n \u251c\u2500 Save game data\n \u2502 \u2502\n \u2502 \u251c\u2500 First save system / Need debugging?\n \u2502 \u2502 \u2192 JSON (Pretty) \u2713\n \u2502 \u2502\n \u2502 \u251c\u2500 Mobile / Size matters?\n \u2502 \u2502 \u2192 Protobuf \u2713\n \u2502 \u2502\n \u2502 \u2514\u2500 Need cross-version compatibility?\n \u2502 \u2192 Protobuf \u2713\n \u2502\n \u251c\u2500 Network messages (multiplayer)\n \u2502 \u2502\n \u2502 \u2514\u2500 Bandwidth is critical\n \u2502 \u2192 Protobuf \u2713\n \u2502\n \u251c\u2500 Editor-only / Temporary cache (trusted environment)\n \u2502 \u2502\n \u2502 \u2514\u2500 Same Unity version, local only\n \u2502 \u2192 SystemBinary (\u26a0\ufe0f legacy, consider JSON Fast)\n \u2502\n \u2514\u2500 Hot path / Per-frame serialization\n \u2502\n \u251c\u2500 Pure C# objects (no Unity types)?\n \u2502 \u2192 JSON (FastPOCO) \u2713\n \u2502\n \u2514\u2500 Mixed with Unity types?\n \u2192 JSON (Fast) \u2713\nFirst-time save system implementation
Use Protobuf for:
Mobile games where save file size matters
Use SystemBinary only for:
using System.Collections.Generic;\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Serialization;\n\npublic class SaveData\n{\n public Vector3 position;\n public Color playerColor;\n public List<GameObject> inventory;\n}\n\nvar data = new SaveData\n{\n position = new Vector3(1, 2, 3),\n playerColor = Color.cyan,\n inventory = new List<GameObject>()\n};\n\n// Serialize to UTF-8 JSON bytes (Unity types supported)\nbyte[] jsonBytes = Serializer.JsonSerialize(data);\n\n// Pretty stringify for human readability\nstring jsonText = Serializer.JsonStringify(data, pretty: true);\n\n// Parse from string (convert to bytes first)\nbyte[] textBytes = System.Text.Encoding.UTF8.GetBytes(jsonText);\nSaveData fromText = Serializer.JsonDeserialize<SaveData>(textBytes);\n\n// File helpers\nSerializer.WriteToJsonFile(data, path: \"save.json\", pretty: true);\nSaveData fromFile = Serializer.ReadFromJsonFile<SaveData>(\"save.json\");\n\n// Generic entry points (choose format at runtime)\nbyte[] bytes = Serializer.Serialize(data, SerializationType.Json);\nSaveData loaded = Serializer.Deserialize<SaveData>(bytes, SerializationType.Json);\nUnity Helpers provides several advanced APIs for high-performance and robust file operations.
"},{"location":"features/serialization/serialization/#async-file-operations","title":"Async File Operations","text":"For non-blocking file I/O (useful in loading screens or background saves):
C#using WallstopStudios.UnityHelpers.Core.Serialization;\n\n// Async read from file\nSaveData data = await Serializer.ReadFromJsonFileAsync<SaveData>(\"save.json\");\n\n// Async write to file\nawait Serializer.WriteToJsonFileAsync(data, \"save.json\", pretty: true);\n\n// With cancellation token (for interruptible operations)\nvar cts = new CancellationTokenSource();\nSaveData data = await Serializer.ReadFromJsonFileAsync<SaveData>(\"save.json\", cts.Token);\nawait Serializer.WriteToJsonFileAsync(data, \"save.json\", pretty: true, cts.Token);\nWhen to use async:
For graceful error handling without try-catch blocks:
C#using WallstopStudios.UnityHelpers.Core.Serialization;\n\n// TryRead - returns false if file missing or invalid JSON\nif (Serializer.TryReadFromJsonFile<SaveData>(\"save.json\", out SaveData data))\n{\n // File exists and parsed successfully\n LoadGame(data);\n}\nelse\n{\n // File missing or corrupted - start new game\n StartNewGame();\n}\n\n// TryWrite - returns false if write failed\nif (!Serializer.TryWriteToJsonFile(data, \"save.json\"))\n{\n Debug.LogError(\"Failed to save game!\");\n ShowSaveErrorDialog();\n}\nWhen to use Try-pattern:
For performance-critical scenarios where you serialize/deserialize frequently:
C#using WallstopStudios.UnityHelpers.Core.Serialization;\n\n// Fast serialize - stricter options, Unity converters, minimal validation\nbyte[] fastBytes = Serializer.JsonSerializeFast(networkMessage);\n\n// Fast deserialize\nNetworkMessage msg = Serializer.JsonDeserializeFast<NetworkMessage>(fastBytes);\n\n// Fast serialize with buffer reuse (zero-allocation after warmup)\nbyte[] buffer = null;\nint length = Serializer.JsonSerializeFast(networkMessage, ref buffer);\n// Use buffer[0..length], buffer is reused on subsequent calls\nFast options differences:
Setting Normal/Pretty Fast Case-insensitive \u2705 \u274c Comments allowed \u2705 \u274c Trailing commas \u2705 \u274c Include fields \u2705 \u274c Reference handling Safe Disabled Unity type converters \u2705 \u2705"},{"location":"features/serialization/serialization/#creating-custom-options","title":"Creating Custom Options","text":"Create your own options based on the Fast presets:
C#using WallstopStudios.UnityHelpers.Core.Serialization;\nusing System.Text.Json;\n\n// Get a copy of Fast options to customize\nJsonSerializerOptions myOptions = Serializer.CreateFastJsonOptions();\nmyOptions.WriteIndented = true; // Add pretty-printing\n\n// FastPOCO - for pure C# objects with NO Unity types (fastest)\nJsonSerializerOptions pocoOptions = Serializer.CreateFastPocoJsonOptions();\n\n// Use with any serialize method\nbyte[] bytes = Serializer.JsonSerialize(data, myOptions);\nSerializer.WriteToJsonFile(data, \"file.json\", myOptions);\nOption profiles:
CreateFastJsonOptions() \u2014 Fast parsing + Unity type converters (Vector3, Color, etc.)CreateFastPocoJsonOptions() \u2014 Fastest, no converters, pure C# objects only// \ud83d\udc0c Normal (most compatible, slightly slower)\nbyte[] normal = Serializer.JsonSerialize(data);\n\n// \ud83d\ude80 Fast (stricter, faster parsing/writing)\nbyte[] fast = Serializer.JsonSerializeFast(data);\n\n// \ud83d\ude80\ud83d\ude80 Fast + buffer reuse (zero-allocation after first call)\nbyte[] buffer = null;\nint len = Serializer.JsonSerializeFast(data, ref buffer);\n\n// \ud83d\ude80\ud83d\ude80\ud83d\ude80 Fast POCO (pure C# objects, no Unity types)\nJsonSerializerOptions pocoOpts = Serializer.CreateFastPocoJsonOptions();\nbyte[] fastest = Serializer.JsonSerialize(pureCSharpData, pocoOpts);\nusing ProtoBuf; // protobuf-net\nusing WallstopStudios.UnityHelpers.Core.Serialization;\n\n[ProtoContract]\npublic class PlayerInfo\n{\n [ProtoMember(1)] public int id;\n [ProtoMember(2)] public string name;\n}\n\nvar info = new PlayerInfo { id = 1, name = \"Hero\" };\nbyte[] buf = Serializer.ProtoSerialize(info);\nPlayerInfo again = Serializer.ProtoDeserialize<PlayerInfo>(buf);\n\n// Generic entry points\nbyte[] buf2 = Serializer.Serialize(info, SerializationType.Protobuf);\nPlayerInfo again2 = Serializer.Deserialize<PlayerInfo>(buf2, SerializationType.Protobuf);\n\n// Buffer reuse (reduce GC in hot paths)\nbyte[] buffer = null;\nint len = Serializer.Serialize(info, SerializationType.Protobuf, ref buffer);\nPlayerInfo sliced = Serializer.Deserialize<PlayerInfo>(buffer.AsSpan(0, len).ToArray(), SerializationType.Protobuf);\n// This package registers protobuf-net surrogates at startup so Unity structs just work in protobuf models.\n// The following Unity types are protobuf-compatible out of the box:\n// - Vector2, Vector3, Vector2Int, Vector3Int\n// - Quaternion\n// - Color, Color32\n// - Rect, RectInt\n// - Bounds, BoundsInt\n// - Resolution\n// Example: use Vector3 directly in a protobuf-annotated model\nusing ProtoBuf; // protobuf-net\nusing UnityEngine; // Unity types\nusing WallstopStudios.UnityHelpers.Core.Serialization;\n\n[ProtoContract]\npublic class NetworkMessage\n{\n [ProtoMember(1)] public int playerId;\n [ProtoMember(2)] public Vector3 position; // Works via registered surrogates\n [ProtoMember(3)] public Quaternion facing; // Works via registered surrogates\n}\n\n// Serialize/deserialize as usual\nvar msg = new NetworkMessage { playerId = 7, position = new Vector3(1,2,3), facing = Quaternion.identity };\nbyte[] bytes = Serializer.ProtoSerialize(msg);\nNetworkMessage again = Serializer.ProtoDeserialize<NetworkMessage>(bytes);\nNotes
Critical for IL2CPP builds (WebGL, iOS, Android, Consoles):
Protobuf uses reflection internally to serialize/deserialize types. Unity's IL2CPP managed code stripping may remove types or fields that are only accessed via reflection, causing silent data loss or runtime crashes in release builds.
Common symptoms:
NullReferenceException or TypeLoadException during Protobuf deserializationIn your Assets folder (or any subfolder), create link.xml to preserve your Protobuf types:
<linker>\n <!-- Preserve all your Protobuf-serialized types -->\n <assembly fullname=\"Assembly-CSharp\">\n <!-- Preserve specific types -->\n <type fullname=\"MyGame.PlayerSave\" preserve=\"all\"/>\n <type fullname=\"MyGame.InventoryData\" preserve=\"all\"/>\n <type fullname=\"MyGame.NetworkMessage\" preserve=\"all\"/>\n\n <!-- Or preserve entire namespace -->\n <namespace fullname=\"MyGame.SaveData\" preserve=\"all\"/>\n </assembly>\n\n <!-- If using Protobuf types across assemblies -->\n <assembly fullname=\"MyGame.Shared\">\n <namespace fullname=\"MyGame.Shared.Protocol\" preserve=\"all\"/>\n </assembly>\n\n <!-- Preserve Unity Helpers if needed -->\n <assembly fullname=\"WallstopStudios.UnityHelpers.Runtime\">\n <!-- Usually not needed, but if you see errors: -->\n <type fullname=\"WallstopStudios.UnityHelpers.Core.Serialization.Serializer\" preserve=\"all\"/>\n </assembly>\n</linker>\nTesting checklist (CRITICAL):
[ProtoContract] type needs preservationWhen you might not need link.xml:
preserve=\"all\"Instead of preserve=\"all\", you can be more selective:
<type fullname=\"MyGame.PlayerSave\">\n <method signature=\"System.Void .ctor()\" preserve=\"all\"/>\n <field name=\"playerId\" />\n <field name=\"level\" />\n <field name=\"inventory\" />\n</type>\nHowever, this is error-prone. Start with preserve=\"all\" and optimize later if build size is critical.
Related documentation:
<a id=\"protobuf-schema-evolution-the-killer-feature\"></a>\n## Protobuf Schema Evolution: The Killer Feature\n\n**The Problem Protobuf Solves:**\n\nYou ship your game with this save format:\n```csharp\n[ProtoContract]\npublic class PlayerSave\n{\n [ProtoMember(1)] public int level;\n [ProtoMember(2)] public string name;\n}\nA month later, you want to add a new feature and change the format:
C#[ProtoContract]\npublic class PlayerSave\n{\n [ProtoMember(1)] public int level;\n [ProtoMember(2)] public string name;\n [ProtoMember(3)] public int gold; // NEW FIELD\n [ProtoMember(4)] public bool isPremium; // NEW FIELD\n}\nWith JSON or BinaryFormatter: Players' existing saves break. You must write migration code or wipe their progress.
With Protobuf: It just works! Old saves load perfectly with gold = 0 and isPremium = false defaults.
Version 1.0 (Launch):
C#[ProtoContract]\npublic class PlayerSave\n{\n [ProtoMember(1)] public string playerId;\n [ProtoMember(2)] public int level;\n [ProtoMember(3)] public Vector3DTO position;\n}\nVersion 1.5 (Inventory System Added):
C#[ProtoContract]\npublic class PlayerSave\n{\n [ProtoMember(1)] public string playerId;\n [ProtoMember(2)] public int level;\n [ProtoMember(3)] public Vector3DTO position;\n [ProtoMember(4)] public List<string> inventory = new(); // NEW: defaults to empty\n}\nVersion 2.0 (Stats Overhaul - level renamed to xp):
C#[ProtoContract]\npublic class PlayerSave\n{\n [ProtoMember(1)] public string playerId;\n // [ProtoMember(2)] int level - REMOVED, but tag 2 is NEVER reused\n [ProtoMember(3)] public Vector3DTO position;\n [ProtoMember(4)] public List<string> inventory = new();\n [ProtoMember(5)] public int xp; // NEW: experience points\n [ProtoMember(6)] public int skillPoints; // NEW: unspent skill points\n}\nResult: Players who saved in v1.0 can load their save in v2.0:
level value (tag 2) is ignoredxp and skillPoints default to 0playerId, position, inventory) loads correctly\u2705 Safe Changes (Always Compatible):
\u26a0\ufe0f Requires Care:
int \u2192 long works, int \u2192 string doesn't)repeated to singular or vice versa (usually breaks)\u274c Never Do This:
required entirely - use validation instead)Handle breaking changes across major versions gracefully:
C#[ProtoContract]\npublic class SaveFile\n{\n [ProtoMember(1)] public int version = 3; // Track your save version\n\n // Version 1-3 fields\n [ProtoMember(2)] public string playerId;\n [ProtoMember(3)] public Vector3DTO position;\n\n // Version 2+ fields\n [ProtoMember(10)] public List<string> inventory;\n\n // Version 3+ fields\n [ProtoMember(20)] public PlayerStats stats;\n\n public void PostDeserialize()\n {\n if (version < 2)\n {\n // Migrate v1 saves: initialize empty inventory\n inventory ??= new List<string>();\n }\n\n if (version < 3)\n {\n // Migrate v2 saves: create default stats\n stats ??= new PlayerStats { xp = 0, level = 1 };\n }\n\n version = 3; // Update to current version\n }\n}\n\u26a0\ufe0f Common Mistake: Don't put migration logic in the constructor. Use PostDeserialize() or a dedicated method called after loading. Constructors don't run during deserialization.
Recommended Testing Pattern:
C#// 1. Save a file with version N:\nvar oldSave = new PlayerSave { level = 10, name = \"Hero\" };\nbyte[] bytes = Serializer.ProtoSerialize(oldSave);\nFile.WriteAllBytes(\"test_v1.save\", bytes);\n\n// 2. Update your schema (add new fields)\n\n// 3. Load the old file with new schema:\nbyte[] oldBytes = File.ReadAllBytes(\"test_v1.save\");\nvar loaded = Serializer.ProtoDeserialize<PlayerSave>(oldBytes);\n\n// New fields have defaults, old fields are preserved\nAssert.AreEqual(10, loaded.level);\nAssert.AreEqual(\"Hero\", loaded.name);\nAssert.AreEqual(0, loaded.gold); // New field defaults to 0\nBest Practice: Keep regression test files \u2014 Store save files from each version in your test suite.
"},{"location":"features/serialization/serialization/#common-save-system-patterns","title":"Common Save System Patterns","text":"Pattern 1: Version-Aware Loading \ud83d\udfe1 Intermediate
C#public SaveFile LoadSave(string path)\n{\n byte[] bytes = File.ReadAllBytes(path);\n SaveFile save = Serializer.ProtoDeserialize<SaveFile>(bytes);\n\n // Perform any version-specific migrations\n save.PostDeserialize();\n\n return save;\n}\nPattern 2: Gradual Migration (preserve old format for rollback) \ud83d\udd34 Advanced
C#public class SaveManager\n{\n public void SaveGame(PlayerData data)\n {\n var protobuf = ConvertToProtobuf(data);\n byte[] bytes = Serializer.ProtoSerialize(protobuf);\n\n // Write both formats during transition period\n File.WriteAllBytes(\"save.dat\", bytes);\n Serializer.WriteToJsonFile(data, \"save.json.backup\");\n }\n}\nPattern 3: Automatic Backup Before Save \ud83d\udfe1 Intermediate
C#public void SaveGame(SaveFile save)\n{\n string path = \"player.save\";\n string backup = $\"player.save.backup_{DateTime.Now:yyyyMMdd_HHmmss}\";\n\n // Backup existing save before overwriting\n if (File.Exists(path))\n {\n File.Copy(path, backup);\n }\n\n byte[] bytes = Serializer.ProtoSerialize(save);\n File.WriteAllBytes(path, bytes);\n\n // Keep only last 3 backups\n CleanupOldBackups(\"player.save.backup_*\", keepCount: 3);\n}\nWithout schema evolution (JSON/BinaryFormatter):
With Protobuf schema evolution:
[ProtoContract] on an abstract base and list all concrete subtypes with [ProtoInclude(tag, typeof(Subtype))].using ProtoBuf;\n\n[ProtoContract]\npublic abstract class Message { }\n\n[ProtoContract]\npublic sealed class Ping : Message { [ProtoMember(1)] public int id; }\n\n[ProtoContract]\n[ProtoInclude(100, typeof(Ping))]\npublic abstract class MessageBase : Message { }\n\n[ProtoContract]\npublic sealed class Envelope { [ProtoMember(1)] public MessageBase payload; }\n\n// round-trip works: Envelope.payload will be Ping at runtime\nbyte[] bytes = Serializer.ProtoSerialize(new Envelope { payload = new Ping { id = 7 } });\nEnvelope again = Serializer.ProtoDeserialize<Envelope>(bytes);\nInterfaces require a root mapping \u2014 Protobuf cannot deserialize directly to an interface because it needs a concrete root. You have three options:
Use an abstract base with [ProtoInclude] and declare fields as that base (preferred).
Register a mapping from the interface to a concrete root type at startup:
Serializer.RegisterProtobufRoot<IMsg, Ping>();\nIMsg msg = Serializer.ProtoDeserialize<IMsg>(bytes);\nIMsg msg = Serializer.ProtoDeserialize<IMsg>(bytes, typeof(Ping));\nAll PRNGs derive from AbstractRandom, which is [ProtoContract] and declares each implementation via [ProtoInclude]. Use this pattern in your models:
[ProtoContract]\npublic class RNGHolder { [ProtoMember(1)] public AbstractRandom rng; }\n\n// Serialize any implementation without surprises\nRNGHolder holder = new RNGHolder { rng = new PcgRandom(seed: 123) };\nbyte[] buf = Serializer.ProtoSerialize(holder);\nRNGHolder rt = Serializer.ProtoDeserialize<RNGHolder>(buf);\nIRandom field, register a root or pass the concrete type when deserializing:Serializer.RegisterProtobufRoot<IRandom, PcgRandom>();\nIRandom r = Serializer.ProtoDeserialize<IRandom>(bytes);\n// or\nIRandom r2 = Serializer.ProtoDeserialize<IRandom>(bytes, typeof(PcgRandom));\nTags in [ProtoInclude(tag, ...)] and [ProtoMember(tag)] are part of your schema. Add new numbers for new types/fields; never reuse or renumber existing tags once shipped.
using WallstopStudios.UnityHelpers.Core.Serialization;\n\nvar obj = new SomeSerializableType();\nbyte[] bin = Serializer.BinarySerialize(obj);\nSomeSerializableType roundtrip = Serializer.BinaryDeserialize<SomeSerializableType>(bin);\n\n// Generic\nbyte[] bin2 = Serializer.Serialize(obj, SerializationType.SystemBinary);\nvar round2 = Serializer.Deserialize<SomeSerializableType>(bin2, SerializationType.SystemBinary);\nWatch-outs
Features
Runtime/Utils/LZMA.cs)References
Runtime/Core/Serialization/Serializer.cs:1Runtime/Utils/LZMA.cs:1System.Text.Json.JsonSerializer calls in app code with Serializer.JsonSerialize/JsonDeserialize/JsonStringify, or with Serializer.Serialize/Deserialize + SerializationType.Json to centralize options and Unity converters.Serializer.ProtoSerialize/ProtoDeserialize or the generic Serializer.Serialize/Deserialize APIs. Ensure models are annotated with [ProtoContract] and stable [ProtoMember(n)] tags.SerializationType.SystemBinary) is deprecated but remains functional for trusted/legacy scenarios. Prefer:SerializationType.Json (System.Text.Json with Unity-aware converters) for readable, diffable content.SerializationType.Protobuf (protobuf-net) for compact, high-performance binary payloads.System.Text.Json can require extra care under AOT (e.g., IL2CPP):
JsonSerializerOptions and concrete generic APIs over object-based serialization to reduce reflection.JsonSerializer calls.System.Type from untrusted input (see TypeConverter); this is intended for trusted configs/tools.This guide explains convex and concave hulls, when to use each, and how they differ.
"},{"location":"features/spatial/hulls/#convex-hull","title":"Convex Hull","text":"Illustration:
"},{"location":"features/spatial/hulls/#concave-hull","title":"Concave Hull","text":"Illustration:
"},{"location":"features/spatial/hulls/#choosing-between-them","title":"Choosing Between Them","text":"All hull helpers now offer both grid-aware (Grid + FastVector3Int) and gridless variants so you can work directly with Vector2/FastVector3Int data:
points.BuildConvexHull(includeColinearPoints: false) for pure Vector2.fastPoints.BuildConvexHull(includeColinearPoints: false) for FastVector3Int without a Grid.fastPoints.BuildConvexHull(grid, includeColinearPoints: false) when you need Grid.CellToWorld conversions.ConvexHullAlgorithm is available for both gridful and gridless overloads.vectorPoints.BuildConcaveHull(options) / BuildConcaveHullKnn / BuildConcaveHullEdgeSplit for Vector2.fastPoints.BuildConcaveHull(options) plus the Knn/EdgeSplit helpers for FastVector3Int without requiring a Grid.fastPoints.BuildConcaveHull(grid, options) remains available when your data lives in grid space.\u26a0\ufe0f The legacy line-division overload BuildConcaveHull(IEnumerable<FastVector3Int>, Grid, float scaleFactor, float concavity) has been retired and now throws NotSupportedException. Switch to ConcaveHullStrategy.Knn or ConcaveHullStrategy.EdgeSplit instead.
Because the new overloads reuse the pooled implementations under the hood, behaviour (winding, pruning, GC profile) matches the grid versions\u2014pick whichever signature best matches your data source.
"},{"location":"features/spatial/hulls/#gridless-vs-grid-aware-quickstart","title":"Gridless vs. Grid-Aware Quickstart","text":"Vector2, Vector3, or FastVector3Int without a Grid). This keeps the hull math independent of Unity\u2019s tile conversion layer.Grid or Tilemap and you want the helper to respect Grid.CellToWorld so you can visualize the hull in scene space.Gridless example \u2014 pure Vector2 data for nav areas or spline fitting:
using System.Collections.Generic;\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Extension;\n\n// outlinePoints could come from mouse clicks or a baked spline\nList<Vector2> outlinePoints = CollectOutlineSamples();\nUnityExtensions.ConcaveHullOptions outlineOptions = UnityExtensions.ConcaveHullOptions.Default\n .WithStrategy(UnityExtensions.ConcaveHullStrategy.EdgeSplit)\n .WithBucketSize(32)\n .WithAngleThreshold(70f);\n\nList<Vector2> hull = outlinePoints.BuildConcaveHull(outlineOptions);\nGrid-aware example \u2014 FastVector3Int tiles aligned to a Grid for tilemaps or voxel data:
using System.Collections.Generic;\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.DataStructure.Adapters;\nusing WallstopStudios.UnityHelpers.Core.Extension;\n\nGrid grid = GetComponent<Grid>();\nList<FastVector3Int> tileSamples = CollectTileCoordinates();\nUnityExtensions.ConcaveHullOptions tileOptions = UnityExtensions.ConcaveHullOptions.Default\n .WithStrategy(UnityExtensions.ConcaveHullStrategy.Knn)\n .WithNearestNeighbors(5);\n\nList<FastVector3Int> gridHull = tileSamples.BuildConcaveHull(grid, tileOptions);\nSee Samples~/Spatial Structures - 2D and 3D/Scripts/HullUsageDemo.cs for a runnable MonoBehaviour that draws both loops (cyan for gridless, yellow for grid-aware) and logs the strategy/neighbor counts so you can copy the pattern directly into your own tooling, or just open Samples~/Spatial Structures - 2D and 3D/Scenes/HullUsageDemo.unity and press Play to watch both flows without extra setup.
includeColinearPoints: true to BuildConvexHull (gridless) or its grid-aware overloads.UnityExtensionsComprehensiveTests.ConvexHullDenseSamplesOnAllEdgesCollapseToCorners (grid) and .Vector2ConvexHullDenseSamplesCollapseToCorners (gridless) cover both paths so you can trust the deterministic behavior.List<FastVector3Int> cornersOnly = gridPoints.BuildConvexHull(grid, includeColinearPoints: false);\nList<FastVector3Int> withEdges = gridPoints.BuildConvexHull(grid, includeColinearPoints: true);\nThis page explains how the 2D and 3D spatial structures compare in terms of correctness, when to use each structure, and why some 3D variants may produce different results for identical inputs and queries.
"},{"location":"features/spatial/spatial-tree-semantics/#result-buffers","title":"Result Buffers","text":"List<T> and clears it before appending results. Reuse the same buffer between calls to avoid garbage and do not expect prior contents to survive a query.QuadTree2D, KdTree2D/3D, OctTree3D, and the RTree variants, matching the log-friendly \u201cprovide your own buffer\u201d approach used throughout the helpers.Illustrations:
3D Variants
Diagram notes
Cons: Hotspots can create deeper trees; nearest-neighbor not optimal vs KDTree.
KDTree2D
Cons: Balanced build costs; dynamic updates more expensive than QuadTree.
RTree2D
While KdTree3D and OctTree3D are both point\u2011based and target equivalent use cases, algorithmic choices can yield different edge\u2011case behavior for identical inputs/queries.
Key reasons and scenarios:
OctTree3D partitions space into eight octants at each node. Points on plane boundaries are classified using octant rules; borderline points may be grouped differently than in KdTree3D.
Bounds queries: half\u2011open vs closed edges
Bounds for traversal. OctTree3D uses BoundingBox3D with inclusive\u2011max conversion and additional node\u2011level fast paths when a node is fully contained.Result impact: points exactly on max edges or at floating\u2011point limits can be included by one structure and excluded by the other in rare cases.
Range (sphere) queries
Both trees use exact per\u2011point distance checks. However, their traversal pruning and \u201cnode fully contained in sphere\u201d checks differ (sphere vs AABB overlap/containment and different numeric guards). For points close to the query radius, minor numeric differences can alter inclusion.
Balanced vs unbalanced KdTree3D
Tips
This practical guide complements performance and semantics pages with diagrams and actionable selection advice.
"},{"location":"features/spatial/spatial-trees-2d-guide/#tldr-what-problem-this-solves","title":"TL;DR \u2014 What Problem This Solves","text":"Quick picks
Points (QuadTree2D / KdTree2D)
C#using WallstopStudios.UnityHelpers.Core.DataStructure;\nusing UnityEngine;\nusing System.Collections.Generic;\n\n// Example element with a position\nstruct Enemy { public Vector2 pos; public int id; }\n\nvar enemies = new List<Enemy>(/* fill with positions */);\n\n// Build a tree from points\nvar quad = new QuadTree2D<Enemy>(enemies, e => e.pos);\nvar kd = new KdTree2D<Enemy>(enemies, e => e.pos); // balanced by default\n\n// Range query (circle)\nvar inRange = new List<Enemy>();\nquad.GetElementsInRange(playerPos, 10f, inRange);\n\n// Bounds (box) query\nvar inBox = new List<Enemy>();\nkd.GetElementsInBounds(new Bounds(center, size), inBox);\n\n// Approximate nearest neighbors\nvar neighbors = new List<Enemy>();\nkd.GetApproximateNearestNeighbors(playerPos, count: 10, neighbors);\nSized objects (RTree2D)
C#using WallstopStudios.UnityHelpers.Core.DataStructure;\nusing UnityEngine;\nusing System.Collections.Generic;\n\nstruct Tile { public Bounds bounds; public int kind; }\n\nvar tiles = new List<Tile>(/* fill with bounds */);\n\n// Build from bounds (AABBs)\nvar rtree = new RTree2D<Tile>(tiles, t => t.bounds);\n\n// Bounds query (fast for large areas)\nvar hits = new List<Tile>();\nrtree.GetElementsInBounds(worldBounds, hits);\n\n// Range query (treats items by their bounds)\nvar near = new List<Tile>();\nrtree.GetElementsInRange(center, radius, near);\nNotes
SpatialHash2D for broad\u2011phase."},{"location":"features/spatial/spatial-trees-2d-guide/#zero-allocation-queries-the-performance-killer-feature","title":"\u2b50 Zero-Allocation Queries: The Performance Killer Feature","text":"
The Problem - GC Spikes Every Frame:
C#void Update()\n{\n // \ud83d\udd34 BAD: Allocates new List every frame\n List<Enemy> nearby = tree.GetElementsInRange(playerPos, 10f);\n\n foreach (Enemy e in nearby)\n {\n e.ReactToPlayer();\n }\n // Result: GC runs frequently = frame drops\n}\nThe Solution - Buffering Pattern:
C#// Reusable buffer (declare once)\nprivate List<Enemy> nearbyBuffer = new(64);\n\nvoid Update()\n{\n nearbyBuffer.Clear();\n\n // \ud83d\udfe2 GOOD: Reuses same List = zero allocations\n tree.GetElementsInRange(playerPos, 10f, nearbyBuffer);\n\n foreach (Enemy e in nearbyBuffer)\n {\n e.ReactToPlayer();\n }\n // Result: No GC, stable 60fps\n}\nImpact:
All spatial trees support this pattern:
QuadTree2D.GetElementsInRange(pos, radius, buffer)KdTree2D.GetElementsInBounds(bounds, buffer)RTree2D.GetElementsInRange(pos, radius, buffer)\ud83d\udca1 Pro Tip: Pre-size your buffers based on expected max results. new List<Enemy>(64) avoids internal resizing for results up to 64 items.
Maximum Ergonomics:
These APIs return the buffer you pass in, so you can use them directly in foreach loops:
private List<Enemy> nearbyBuffer = new(64);\n\nvoid Update()\n{\n // Returns the same buffer - use it directly in foreach!\n foreach (Enemy e in tree.GetElementsInRange(playerPos, 10f, nearbyBuffer))\n {\n e.ReactToPlayer();\n }\n}\nUsing Pooled Buffers:
Don't want to manage buffers yourself? Use the built-in pooling utilities:
C#using WallstopStudios.UnityHelpers.Utils;\n\nvoid Update()\n{\n // Get pooled buffer - automatically returned when scope exits\n using var lease = Buffers<Enemy>.List.Get(out List<Enemy> buffer);\n\n // Use it directly in foreach - combines zero-alloc query + pooled buffer!\n foreach (Enemy e in tree.GetElementsInRange(playerPos, 10f, buffer))\n {\n e.ReactToPlayer();\n }\n // buffer automatically returned to pool here\n}\nSee Buffering Pattern for the complete guide and Pooling Utilities for more pooling options.
"},{"location":"features/spatial/spatial-trees-2d-guide/#structures","title":"Structures","text":""},{"location":"features/spatial/spatial-trees-2d-guide/#quadtree2d","title":"QuadTree2D","text":"Diagram:
"},{"location":"features/spatial/spatial-trees-2d-guide/#kdtree2d","title":"KDTree2D","text":"Diagram:
"},{"location":"features/spatial/spatial-trees-2d-guide/#rtree2d","title":"RTree2D","text":"Diagram:
"},{"location":"features/spatial/spatial-trees-2d-guide/#choosing-a-structure","title":"Choosing a Structure","text":"Use this decision flowchart to pick the right spatial tree:
Text OnlySTART: Do your objects move frequently?\n \u2502\n \u251c\u2500 YES \u2192 Consider SpatialHash2D instead (see README)\n \u2502 (Spatial trees require rebuild on movement)\n \u2502\n \u2514\u2500 NO \u2192 Continue to next question\n \u2502\n \u2514\u2500 What type of queries do you need?\n \u2502\n \u251c\u2500 Primarily nearest neighbor (k-NN)\n \u2502 \u2502\n \u2502 \u251c\u2500 Static data, want consistent performance\n \u2502 \u2502 \u2192 KDTree2D (Balanced) \u2713\n \u2502 \u2502\n \u2502 \u2514\u2500 Data changes occasionally, need fast rebuilds\n \u2502 \u2192 KDTree2D (Unbalanced) \u2713\n \u2502\n \u251c\u2500 Do objects have size/bounds (not just points)?\n \u2502 \u2502\n \u2502 \u251c\u2500 YES \u2192 Need bounds intersection queries\n \u2502 \u2502 \u2192 RTree2D \u2713\n \u2502 \u2502\n \u2502 \u2514\u2500 NO \u2192 Continue\n \u2502\n \u2514\u2500 General range/circular queries, broad-phase\n \u2192 QuadTree2D \u2713 (best all-around choice)\nFor deeper details, performance data, and diagrams, see:
This approachable guide shows when to use OctTree3D, KdTree3D, and RTree3D, with quick code you can copy.
"},{"location":"features/spatial/spatial-trees-3d-guide/#tldr-what-problem-this-solves","title":"TL;DR \u2014 What Problem This Solves","text":"Quick picks
Points (OctTree3D / KdTree3D)
C#using WallstopStudios.UnityHelpers.Core.DataStructure;\nusing UnityEngine;\nusing System.Collections.Generic;\n\nstruct VfxPoint { public Vector3 pos; public int id; }\n\nvar points = new List<VfxPoint>(/* fill with positions */);\n\n// Build trees from points\nvar oct = new OctTree3D<VfxPoint>(points, p => p.pos);\nvar kd = new KdTree3D<VfxPoint>(points, p => p.pos); // balanced by default\n\n// Range query (sphere)\nvar inRange = new List<VfxPoint>();\noct.GetElementsInRange(playerPos, 12f, inRange);\n\n// Bounds (box) query\nvar inBox = new List<VfxPoint>();\nkd.GetElementsInBounds(new Bounds(center, size), inBox);\n\n// Approximate nearest neighbors\nvar neighbors = new List<VfxPoint>();\nkd.GetApproximateNearestNeighbors(playerPos, count: 12, neighbors);\nSized objects (RTree3D)
C#using WallstopStudios.UnityHelpers.Core.DataStructure;\nusing UnityEngine;\nusing System.Collections.Generic;\n\nstruct Volume { public Bounds bounds; public int kind; }\n\nvar volumes = new List<Volume>(/* fill with bounds */);\n\n// Build from 3D bounds (AABBs)\nvar rtree = new RTree3D<Volume>(volumes, v => v.bounds);\n\n// Bounds query (fast for large volumes)\nvar hits = new List<Volume>();\nrtree.GetElementsInBounds(worldBounds, hits);\n\n// Range query (treats items by their bounds)\nvar near = new List<Volume>();\nrtree.GetElementsInRange(center, radius, near);\nNotes
SpatialHash3D for broad\u2011phase neighborhood queries.All 3D spatial trees support the same zero-allocation query pattern as their 2D counterparts. Pass a reusable buffer to avoid GC allocations:
C#// Reusable buffer (declare once)\nprivate List<VfxPoint> nearbyBuffer = new(128);\n\nvoid Update()\n{\n nearbyBuffer.Clear();\n\n // \ud83d\udfe2 GOOD: Reuses same List = zero allocations\n tree.GetElementsInRange(playerPos, 15f, nearbyBuffer);\n\n foreach (VfxPoint p in nearbyBuffer)\n {\n p.UpdateEffect();\n }\n}\nAll 3D spatial trees support buffered queries:
OctTree3D.GetElementsInRange(pos, radius, buffer)KdTree3D.GetElementsInBounds(bounds, buffer)RTree3D.GetElementsInRange(pos, radius, buffer)\ud83d\udcd6 For the complete buffering guide including pooled buffers and GC impact analysis, see:
This guide covers several foundational data structures used across the library and when to use them.
"},{"location":"features/utilities/data-structures/#cyclic-buffer-ring-buffer","title":"Cyclic Buffer (Ring Buffer)","text":"When to use vs. DotNET queues
CyclicBuffer<T> over Queue<T> when you want bounded memory with O(1) push/pop at both ends and predictable behavior under backpressure (drop/overwrite oldest, or pop proactively).Queue<T> when you need unbounded growth without wrap semantics.API snapshot
C#using WallstopStudios.UnityHelpers.Core.DataStructure;\n\nvar rb = new CyclicBuffer<int>(capacity: 4);\nrb.Add(10); rb.Add(20); rb.Add(30);\n\n// Pop from front/back\nif (rb.TryPopFront(out var first)) { /* first == 10 */ }\nif (rb.TryPopBack(out var last)) { /* last == 30 */ }\n\n// Remove by value / predicate\nrb.Add(40); rb.Add(50);\nrb.Remove(20); // O(n) compacting via temp buffer\nrb.RemoveAll(x => x % 2 == 0); // remove evens\n\n// Resize in place (may drop tail elements)\nrb.Resize(8);\nTips and pitfalls
Add will wrap and overwrite the oldest only once capacity is reached; use TryPopFront periodically to keep buffer from evicting data you still need.Remove/RemoveAll are O(n); keep hot paths to Add/TryPop* when possible.When to use vs Queue<T> / Stack<T>
Deque<T> when you need both push_front and push_back in O(1) amortized.Queue<T> for simple FIFO; Stack<T> for LIFO only.API snapshot
C#using WallstopStudios.UnityHelpers.Core.DataStructure;\n\nvar dq = new Deque<string>(capacity: 8);\ndq.PushFront(\"start\");\ndq.PushBack(\"end\");\n\nif (dq.TryPopFront(out var a)) { /* a == \"start\" */ }\nif (dq.TryPopBack(out var b)) { /* b == \"end\" */ }\n\n// Peeking without removal\ndq.PushBack(\"x\");\nif (dq.TryPeekFront(out var f)) { /* f == \"x\" */ }\nTips
TrimExcess() after spikes to return memory.When to use vs SortedSet<T>
Heap<T>/PriorityQueue<T> for frequent push/pop top in O(log n) with low overhead.SortedSet<T> for ordered iteration and fast remove arbitrary item (by key), at higher constants.API snapshot (Heap)
C#using WallstopStudios.UnityHelpers.Core.DataStructure;\n\nvar minHeap = new Heap<int>(); // default comparer => min-heap\nminHeap.Add(5); minHeap.Add(2); minHeap.Add(9);\n\nif (minHeap.TryPop(out var top)) { /* top == 2 */ }\nif (minHeap.TryPeek(out var peek)) { /* peek == 5 */ }\nAPI snapshot (PriorityQueue)
C#using WallstopStudios.UnityHelpers.Core.DataStructure;\n\nvar pq = PriorityQueue<(int priority, string job)>.CreateMin(\n capacity: 32\n);\npq.Enqueue((1, \"emergency\"));\npq.Enqueue((5, \"later\"));\npq.TryDequeue(out var item); // (1, \"emergency\")\nTips
PriorityQueue<T>.CreateMax() to flip ordering without writing a custom comparer.When to use
API snapshot (int-based)
C#using WallstopStudios.UnityHelpers.Core.DataStructure;\n\nvar uf = new DisjointSet(n: 6); // elements 0..5\nuf.TryUnion(0, 1);\nuf.TryUnion(2, 3);\nuf.TryIsConnected(0, 3, out var conn); // false\nuf.TryUnion(1, 3);\nuf.TryIsConnected(0, 3, out conn); // true\nAPI snapshot (generic)
C#using WallstopStudios.UnityHelpers.Core.DataStructure;\n\nvar people = new[] { \"Ana\", \"Bo\", \"Cy\" };\nvar uf = new DisjointSet<string>(people);\nuf.TryUnion(\"Ana\", \"Bo\");\nuf.TryIsConnected(\"Ana\", \"Cy\", out var conn); // false\nTips
When to use vs HashSet<T>
SparseSet when your IDs are small integers (0..N) and you need O(1) contains with dense, cache-friendly iteration over active items.HashSet<T> for arbitrary keys, very large/unbounded key spaces, or when memory for sparse cannot scale to the max ID.API snapshot (int IDs)
C#using WallstopStudios.UnityHelpers.Core.DataStructure;\n\nvar set = new SparseSet(capacity: 1000); // supports IDs in [0,1000)\nset.TryAdd(42); // returns bool indicating success\nbool has42 = set.Contains(42); // true\nset.TryRemove(42); // returns bool indicating success\n\n// Dense iteration order over active IDs\nforeach (int id in set) { /* ... */ }\nAPI snapshot (generic values)
C#var set = new SparseSet<MyComponent>(capacity: 1024);\nset.TryAdd(100, new MyComponent()); // key 100 -> value, returns bool\nvar comp = set[0]; // dense index 0 value\nTips
When to use vs dictionaries
Trie for lots of prefix queries and auto-complete where per-character traversal beats repeated hashing.Dictionary<string, T> when you rarely do prefix scans and primarily need exact lookup.API snapshot
C#using WallstopStudios.UnityHelpers.Core.DataStructure;\n\n// Words only\nvar words = new Trie(new[] { \"cat\", \"car\", \"dog\" });\nbool hasDog = words.Contains(\"dog\"); // true\nList<string> outWords = new();\nwords.GetWordsWithPrefix(\"ca\", outWords); // outWords = [\"cat\",\"car\"]\n\n// Key -> Value\nvar items = new Dictionary<string, int> { [\"apple\"] = 1, [\"apricot\"] = 2 };\nvar trie = new Trie<int>(items);\nif (trie.TryGetValue(\"apricot\", out var v)) { /* 2 */ }\nList<int> values = new();\ntrie.GetValuesWithPrefix(\"ap\", values); // values = [1,2]\nTips
When to use vs bool[] / HashSet<int>
BitSet for dense boolean sets with fast bitwise ops (masks, layers, filters) and compact storage.bool[] for tiny, fixed schemas you manipulate rarely; use HashSet<int> for sparse, very large universes.API snapshot
C#using WallstopStudios.UnityHelpers.Core.DataStructure;\n\nvar bits = new BitSet(initialCapacity: 128);\nbits[3] = true; // indexer calls TrySet/TryClear\nbits.TrySet(64);\nbool any = bits.Any(); // any bit set?\nint count = bits.CountSetBits();\n\n// Bitwise ops\nbits.Not(); // invert\nbits.LeftShift(2); // multiply-by-4 mask window\nbits.RightShift(1);\nTips
Common pitfalls
Remove/RemoveAll are O(n); keep hot paths to TryPop/Add.Notes on constants
flowchart LR\n subgraph Cache Operations\n Get[Get] --> Hit{Hit?}\n Hit -->|Yes| Return[Return Value]\n Hit -->|No| Load[Load/Miss]\n Set[Set] --> Evict{At Capacity?}\n Evict -->|Yes| Policy[Apply Eviction Policy]\n Evict -->|No| Store[Store Entry]\n Policy --> Store\n endCache<TKey, TValue> when you need automatic eviction, expiration, or access tracking.Dictionary<TKey, TValue> for simple lookups without size limits or expiration.ConcurrentDictionary<TKey, TValue> for thread-safe access without cache semantics.using WallstopStudios.UnityHelpers.Core.DataStructure;\n\n// Simple LRU cache with fluent builder\nCache<string, UserData> cache = CacheBuilder<string, UserData>.NewBuilder()\n .MaximumSize(1000)\n .ExpireAfterWrite(TimeSpan.FromMinutes(5))\n .EvictionPolicy(EvictionPolicy.Lru)\n .Build();\n\n// Basic operations\ncache.Set(\"user1\", userData);\nif (cache.TryGet(\"user1\", out UserData data))\n{\n // Use cached data\n}\n\ncache.TryRemove(\"user1\");\ncache.Clear();\nusing WallstopStudios.UnityHelpers.Core.DataStructure;\n\n// Loading cache - auto-computes missing values\nCache<int, ExpensiveResult> loadingCache = CacheBuilder<int, ExpensiveResult>.NewBuilder()\n .MaximumSize(100)\n .Build(key => ComputeExpensiveResult(key));\n\n// GetOrAdd uses the loader when key is missing\nExpensiveResult result = loadingCache.GetOrAdd(42, null);\nusing WallstopStudios.UnityHelpers.Core.DataStructure;\n\nCache<string, PathResult> pathCache = CacheBuilder<string, PathResult>.NewBuilder()\n .MaximumSize(2000)\n .InitialCapacity(64) // Start small, grow as needed\n .ExpireAfterWrite(300f) // 5 minutes TTL\n .WithJitter(12f) // Prevent thundering herd\n .EvictionPolicy(EvictionPolicy.Slru) // Scan-resistant eviction\n .ProtectedRatio(0.8f) // 80% protected segment for SLRU\n .AllowGrowth(1.5f, 4000) // Grow 1.5x up to 4000 when thrashing\n .RecordStatistics() // Enable hit/miss tracking\n .OnEviction((key, value, reason) => Debug.Log($\"Evicted {key}: {reason}\"))\n .OnGet((key, value) => Debug.Log($\"Cache hit: {key}\"))\n .OnSet((key, value) => Debug.Log($\"Cache set: {key}\"))\n .Build();\n\n// Access statistics\nCacheStatistics stats = pathCache.GetStatistics();\nDebug.Log($\"Hit rate: {stats.HitRate:P1}, Evictions: {stats.EvictionCount}\");\nusing WallstopStudios.UnityHelpers.Core.DataStructure;\n\n// Weight-based eviction (e.g., by byte size)\nCache<string, Texture2D> textureCache = CacheBuilder<string, Texture2D>.NewBuilder()\n .MaximumWeight(100_000_000) // 100 MB total\n .Weigher((key, tex) => tex.width * tex.height * 4) // Bytes per texture\n .ExpireAfterAccess(TimeSpan.FromMinutes(10)) // Sliding window\n .Build();\nUse CachePresets for common scenarios:
using WallstopStudios.UnityHelpers.Core.DataStructure;\n\n// Short-lived cache: 100 entries, 60s TTL, LRU\nCache<int, Vector3> tempCache = CachePresets.ShortLived<int, Vector3>().Build();\n\n// Long-lived cache: 1000 entries, no TTL, LRU\nCache<string, GameObject> prefabCache = CachePresets.LongLived<string, GameObject>()\n .Build(key => Resources.Load<GameObject>($\"Prefabs/{key}\"));\n\n// Session cache: 500 entries, 30 min sliding window, LRU\nCache<string, InventoryData> sessionCache = CachePresets.SessionCache<string, InventoryData>().Build();\n\n// High-throughput: 2000 entries, 5 min TTL, SLRU, growth enabled\nCache<(Vector3, Vector3), NavMeshPath> pathCache = CachePresets.HighThroughput<(Vector3, Vector3), NavMeshPath>().Build();\n\n// Render cache: 200 entries, 30s TTL, FIFO\nCache<int, MaterialPropertyBlock> renderCache = CachePresets.RenderCache<int, MaterialPropertyBlock>().Build();\n\n// Network cache: 100 entries, 2 min TTL with jitter, LRU\nCache<string, JsonResponse> apiCache = CachePresets.NetworkCache<string, JsonResponse>().Build();\nCount Current number of entries Size Total weight (weighted caching) or count MaximumSize Configured maximum entries Capacity Current internal capacity (may be < MaximumSize) Keys Enumerable of all keys (allocates state machine) TryGet(key, out value) Returns true if key exists and not expired Set(key, value) Adds or updates an entry GetOrAdd(key, factory) Gets existing or computes and caches new value (factory optional with loader) TryRemove(key) Removes entry if present, returns bool TryRemove(key, out value) Removes entry and returns the removed value ContainsKey(key) Checks if key exists Clear() Removes all entries CleanUp() Forces expiration scan Compact(ratio) Evicts percentage of entries Resize(newSize) Changes maximum size GetStatistics() Returns hit/miss/eviction stats (if enabled) GetAll(keys, dict) Batch get into provided dictionary SetAll(items) Batch set from collection GetKeys(list) Zero-allocation key enumeration into provided list"},{"location":"features/utilities/data-structures/#tips-and-pitfalls","title":"Tips and pitfalls","text":"CachePresets provides optimized defaults for common scenarios.MaximumWeight + Weigher for size-based eviction (e.g., texture bytes).OnEviction, OnGet, OnSet run on the calling thread.Static helper classes and utilities that solve common programming problems without needing components on GameObjects. Use these for predictive aiming, path utilities, threading, hashing, formatting, and more.
"},{"location":"features/utilities/helper-utilities/#contents","title":"Contents","text":"Buffers.GetWaitForSeconds* cachingUnity allocates a new WaitForSeconds/WaitForSecondsRealtime every time you yield with a literal. Buffers.GetWaitForSeconds(...) and Buffers.GetWaitForSecondsRealTime(...) pool those instructions to reduce coroutine allocations, but each distinct duration used to stick around forever. Large ranges (randomized cooldowns, tweens, etc.) could leak thousands of instances.
New pooling policy knobs (Runtime 2.2.1+):
Setting Default PurposeBuffers.WaitInstructionMaxDistinctEntries 512 Upper bound on distinct cached durations. Set to 0 to disable the cap, or tighten it for editor/dev builds. When the limit is reached the cache stops growing (or evicts, if LRU is enabled). Buffers.WaitInstructionQuantizationStepSeconds 0 (off) Rounds requested durations to the nearest step before caching. Useful when you can tolerate millisecond snapping (e.g., .005f \u2192 .01f). Buffers.WaitInstructionUseLruEviction false When true, the cache becomes an LRU: it evicts the least recently used duration whenever it hits the max entry count instead of rejecting new ones. Diagnostics expose the eviction count. Buffers.TryGetWaitForSecondsPooled(float seconds) / TryGetWaitForSecondsRealtimePooled n/a Returns the cached instruction or null if the request would exceed the cap. Use this when you want to detect \u201cunsafe\u201d usages and allocate manually instead. Buffers.WaitForSecondsCacheDiagnostics / .WaitForSecondsRealtimeCacheDiagnostics snapshot Exposes DistinctEntries, MaxDistinctEntries, LimitRefusals, and whether quantization is active so you can surface metrics in your own tooling. \u2699\ufe0f Project-wide defaults: Open the Coroutine Wait Instruction Buffers foldout under Project Settings \u25b8 Wallstop Studios \u25b8 Unity Helpers to edit these knobs. The settings asset lives at Resources/Wallstop Studios/Unity Helpers/UnityHelpersBufferSettings.asset, ships with your build, and automatically applies on script/domain reload or when a player starts (unless your code overrides the values at runtime). Use Apply Defaults Now to push the current sliders into the active domain or Capture Current Values to snapshot whatever Buffers is using in play mode.
\ud83d\udd12 Persistence Behavior: When you click Apply Defaults Now, the settings are immediately:
AssetDatabase.SaveAssets()Buffers.WaitInstruction* properties are updated immediatelyThis ensures settings persist across:
[InitializeOnLoadMethod]Resources/ and auto-applies via [RuntimeInitializeOnLoadMethod]Toggle Apply On Load to control whether the saved defaults auto-apply when the domain loads. If disabled, the asset serves as a reference and you must call asset.ApplyToBuffers() manually.
// Clamp the cache to 128 distinct waits, quantize to milliseconds, and reuse LRU entries.\nBuffers.WaitInstructionMaxDistinctEntries = 128;\nBuffers.WaitInstructionQuantizationStepSeconds = 0.001f;\nBuffers.WaitInstructionUseLruEviction = true;\n\nIEnumerator WeaponCooldown(Func<float> cooldownSeconds)\n{\n float waitSeconds = cooldownSeconds();\n\n // Prefer pooled waits, but fall back to a fresh instance if the cache refuses it.\n WaitForSeconds pooled = Buffers.TryGetWaitForSecondsPooled(waitSeconds)\n ?? new WaitForSeconds(waitSeconds);\n\n yield return pooled;\n}\n\nvoid OnGUI()\n{\n WaitInstructionCacheDiagnostics stats = Buffers.WaitForSecondsCacheDiagnostics;\n GUILayout.Label(\n $\"Wait cache: {stats.DistinctEntries}/{stats.MaxDistinctEntries} (refusals={stats.LimitRefusals}, evictions={stats.Evictions})\"\n );\n}\n\u26a0\ufe0f Limit warnings: In Editor and Development builds the first limit hit (and every 25th after) emits a warning so you can spot misuses quickly. Production builds skip the log to avoid noise.
\u2705 Deterministic fallback: When the cache refuses a duration, Buffers.GetWaitForSeconds* still returns a valid instruction\u2014it just isn\u2019t cached, so highly variable waits no longer lead to unbounded memory growth.
What it does: Calculates where to aim when shooting at a moving target, accounting for projectile travel time.
Problem it solves: Shooting a bullet at where an enemy is misses if they're moving. You need to aim at where they will be.
C#using WallstopStudios.UnityHelpers.Core.Helper;\n\nVector2 enemyPos = enemy.transform.position;\nVector2 enemyVelocity = enemy.GetComponent<Rigidbody2D>().velocity;\nVector2 turretPos = turret.transform.position;\nfloat bulletSpeed = 20f;\n\nVector2? aimPosition = Helpers.PredictCurrentTarget(\n enemyPos,\n enemyVelocity,\n turretPos,\n bulletSpeed\n);\n\nif (aimPosition.HasValue)\n{\n // Aim at aimPosition to hit the moving target\n Vector2 aimDirection = (aimPosition.Value - turretPos).normalized;\n FireProjectile(aimDirection, bulletSpeed);\n}\nelse\n{\n // Target is too fast, can't hit\n}\nWhen to use:
When NOT to use:
Get random points in circles/spheres:
C#using WallstopStudios.UnityHelpers.Core.Helper;\n\n// Random point inside circle (uniform distribution)\nVector2 spawnPoint = Helpers.GetRandomPointInCircle(center, radius);\n\n// Random point inside sphere (uniform distribution)\nVector3 explosionPoint = Helpers.GetRandomPointInSphere(center, radius);\nUse for:
Get rotation speed for smooth turning:
C#using WallstopStudios.UnityHelpers.Core.Helper;\n\n// Calculate how much to rotate this frame toward target\nfloat currentAngle = transform.eulerAngles.z;\nfloat targetAngle = GetTargetAngle();\nfloat maxDegreesPerSecond = 180f;\n\nfloat newAngle = Helpers.GetAngleWithSpeed(\n currentAngle,\n targetAngle,\n maxDegreesPerSecond,\n Time.deltaTime\n);\n\ntransform.eulerAngles = new Vector3(0, 0, newAngle);\nHandles:
Execute code after delay or next frame:
C#using WallstopStudios.UnityHelpers.Core.Helper;\n\n// Execute after 2 seconds\nHelpers.ExecuteFunctionAfterDelay(\n monoBehaviour,\n () => Debug.Log(\"Delayed!\"),\n delayInSeconds: 2f\n);\n\n// Execute next frame\nHelpers.ExecuteFunctionNextFrame(\n monoBehaviour,\n () => Debug.Log(\"Next frame!\")\n);\nUses coroutines under the hood.
"},{"location":"features/utilities/helper-utilities/#repeating-execution-with-jitter","title":"Repeating Execution with Jitter","text":"Run function repeatedly with random timing variance:
C#using WallstopStudios.UnityHelpers.Core.Helper;\n\n// Spawn enemy every 5-8 seconds\nHelpers.StartFunctionAsCoroutine(\n gameManager,\n SpawnEnemy,\n baseInterval: 5f,\n intervalJitter: 3f // Random \u00b13 seconds\n);\n\nvoid SpawnEnemy()\n{\n Instantiate(enemyPrefab, spawnPoint.position, Quaternion.identity);\n}\nUse for:
using WallstopStudios.UnityHelpers.Core.Helper;\n\n// Get all layer names (cached after first call)\nstring[] allLayers = Helpers.GetAllLayerNames();\n\n// Get all sprite label names (editor only, cached)\nstring[] labels = Helpers.GetAllSpriteLabelNames();\nUse for:
Update PolygonCollider2D to match sprite:
C#using WallstopStudios.UnityHelpers.Core.Helper;\n\nSpriteRenderer renderer = GetComponent<SpriteRenderer>();\nPolygonCollider2D collider = GetComponent<PolygonCollider2D>();\n\nHelpers.UpdateShapeToSprite(renderer, collider);\n// Collider now matches sprite's physics shape\nTag-based component finding with caching:
C#using WallstopStudios.UnityHelpers.Core.Helper;\n\n// First call searches scene, subsequent calls use cache\nPlayer player = Helpers.Find<Player>(\"Player\");\n\n// Clear cache manually if needed\nHelpers.ClearInstance<Player>();\n\n// Set cache manually (for dependency injection scenarios)\nHelpers.SetInstance(playerInstance);\nPerformance: First call searches the scene using GameObject.FindWithTag; subsequent calls use a cached O(1) dictionary lookup. The cache persists until manually cleared.
"},{"location":"features/utilities/helper-utilities/#component-existence-checks","title":"Component Existence Checks","text":"C#using WallstopStudios.UnityHelpers.Core.Helper;\n\n// Check if component exists without allocating\nbool hasRigidbody = Helpers.HasComponent<Rigidbody2D>(gameObject);\n\n// Better than:\nbool hasRigidbody = GetComponent<Rigidbody2D>() != null; // Allocates\nusing WallstopStudios.UnityHelpers.Core.Helper;\n\n// Get existing component or add if missing\nRigidbody2D rb = Helpers.GetOrAddComponent<Rigidbody2D>(gameObject);\nRecursively enable/disable components:
C#using WallstopStudios.UnityHelpers.Core.Helper;\n\n// Enable all Collider2D components in children\nHelpers.EnableRecursively<Collider2D>(rootObject, enable: true);\n\n// Disable all renderers in hierarchy\nHelpers.EnableRendererRecursively<SpriteRenderer>(rootObject, enable: false);\nUse for:
using WallstopStudios.UnityHelpers.Core.Helper;\n\n// Destroy all children (useful for clearing containers)\nHelpers.DestroyAllChildrenGameObjects(parentTransform);\nUse for:
Editor/runtime aware destruction:
C#using WallstopStudios.UnityHelpers.Core.Helper;\n\n// Uses DestroyImmediate in editor, Destroy in play mode\nHelpers.SmartDestroy(gameObject);\n\n// Also handles assets correctly (won't destroy project assets)\nUse in editor tools to avoid \"Destroying assets is not permitted\" errors.
"},{"location":"features/utilities/helper-utilities/#prefab-utilities","title":"Prefab Utilities","text":"C#using WallstopStudios.UnityHelpers.Core.Helper;\n\n// Check if GameObject is a prefab asset or instance\nbool isPrefab = Helpers.IsPrefab(gameObject);\n\n// Safely modify prefab (editor only)\n#if UNITY_EDITOR\nHelpers.ModifyAndSavePrefab(prefabAssetPath, prefab =>\n{\n // Modify prefab here\n var component = prefab.AddComponent<MyComponent>();\n component.value = 42;\n // Changes saved automatically\n});\n#endif\nVisit all children recursively:
C#using WallstopStudios.UnityHelpers.Core.Helper;\n\n// Depth-first traversal (visits deepest children first)\nHelpers.IterateOverAllChildrenRecursively<SpriteRenderer>(rootTransform, renderer =>\n{\n renderer.color = Color.red;\n});\n\n// Buffered version (reduces allocations)\nusing (var buffer = Buffers<Transform>.List.Get())\n{\n Helpers.IterateOverAllChildrenRecursively(rootTransform, buffer.Value);\n foreach (Transform child in buffer.Value)\n {\n // Process children\n }\n}\nVisit by depth level:
C#using WallstopStudios.UnityHelpers.Core.Helper;\n\n// Breadth-first traversal with depth limit\nHelpers.IterateOverAllChildrenRecursivelyBreadthFirst(\n rootTransform,\n transform => Debug.Log(transform.name),\n maxDepth: 3 // Only visit 3 levels deep\n);\nUse for:
Walk up the hierarchy:
C#using WallstopStudios.UnityHelpers.Core.Helper;\n\n// Find component in parents\nHelpers.IterateOverAllParentComponentsRecursively<Canvas>(transform, canvas =>\n{\n Debug.Log($\"Found canvas: {canvas.name}\");\n});\n\n// Get all parents (no component filter)\nusing (var buffer = Buffers<Transform>.List.Get())\n{\n Helpers.IterateOverAllParents(transform, buffer.Value);\n // buffer contains all parent transforms up to root\n}\nUse for:
using WallstopStudios.UnityHelpers.Core.Helper;\n\n// Get immediate children (non-recursive)\nusing (var buffer = Buffers<Transform>.List.Get())\n{\n Helpers.IterateOverAllChildren(transform, buffer.Value);\n // Only direct children, no grandchildren\n}\nExecute code on Unity's main thread from background threads:
Problem it solves: Unity APIs can only be called from the main thread. Background Tasks/threads can't directly manipulate GameObjects. This marshals callbacks back to the main thread.
See the dedicated Unity Main Thread Dispatcher guide for details about auto-creation, queue limits, the AutoCreationScope helper, and the CreateTestScope(...) convenience method that packages can use in their own test fixtures.
using WallstopStudios.UnityHelpers.Core.Helper;\nusing System.Threading.Tasks;\n\nasync Task LoadDataInBackground()\n{\n // Background thread work\n await Task.Run(() =>\n {\n // Expensive computation\n var data = LoadFromDatabase();\n\n // Need to update UI - marshal back to main thread\n UnityMainThreadDispatcher.Instance.RunOnMainThread(() =>\n {\n // Safe to call Unity APIs here\n uiText.text = data.ToString();\n });\n });\n}\nAsync version with result:
C#async Task<string> GetTextFromMainThread()\n{\n // Called from background thread, executes on main thread\n string text = await UnityMainThreadDispatcher.Instance.Post(() =>\n {\n return uiText.text; // Safe to access Unity objects\n });\n\n return text;\n}\nUse the Logging Extensions guide for:
$\"{value:b,color=red}\")this.Log, this.LogWarn, this.LogError, this.LogDebug)These helpers rely on the same dispatcher utilities above, so logging from jobs/background threads stays safe.
Fire-and-forget on main thread:
C#// From background thread\nUnityMainThreadDispatcher.Instance.RunOnMainThread(() =>\n{\n Instantiate(prefab, position, rotation);\n});\nWhen to use:
Important:
Normalize path separators:
C#using WallstopStudios.UnityHelpers.Core.Helper;\n\nstring windowsPath = @\"Assets\\Sprites\\Player.png\";\nstring unityPath = PathHelper.Sanitize(windowsPath);\n// Result: \"Assets/Sprites/Player.png\"\nUnity prefers forward slashes. Use this for cross-platform paths.
"},{"location":"features/utilities/helper-utilities/#directory-utilities","title":"Directory Utilities","text":"Create directories safely:
C#using WallstopStudios.UnityHelpers.Core.Helper;\n\n#if UNITY_EDITOR\n// Creates directory and updates AssetDatabase\nDirectoryHelper.EnsureDirectoryExists(\"Assets/Generated/Data\");\n#endif\nFind package root:
C#// Walk hierarchy to find package.json\nstring packageRoot = DirectoryHelper.FindPackageRootPath();\n// Returns path to package containing calling script\nUse for:
Convert between absolute and Unity-relative paths:
C#using WallstopStudios.UnityHelpers.Core.Helper;\n\nstring absolute = \"C:/Projects/MyGame/Assets/Textures/player.png\";\nstring relative = DirectoryHelper.AbsoluteToUnityRelativePath(absolute);\n// Result: \"Assets/Textures/player.png\"\nGet calling script's directory:
C#// Uses [CallerFilePath] magic\nstring scriptDir = DirectoryHelper.GetCallerScriptDirectory();\n// Returns directory containing the calling .cs file\nInitialize file if missing:
C#using WallstopStudios.UnityHelpers.Core.Helper;\n\n// Create config.json with default contents if it doesn't exist\nFileHelper.InitializePath(\n \"Assets/config.json\",\n \"{ \\\"version\\\": 1 }\"\n);\nAsync file copy:
C#using System.Threading;\n\nCancellationTokenSource cts = new CancellationTokenSource();\n\nawait FileHelper.CopyFileAsync(\n \"source.txt\",\n \"destination.txt\",\n bufferSize: 81920, // 80KB buffer\n cts.Token\n);\nUse for:
Check if scene is loaded:
C#using WallstopStudios.UnityHelpers.Core.Helper;\n\nbool loaded = SceneHelper.IsSceneLoaded(\"GameLevel\");\n// Checks by scene name or path\nGet all scene paths (editor):
C##if UNITY_EDITOR\nstring[] allScenes = SceneHelper.GetAllScenePaths();\n// Returns all .unity files in project\n\nstring[] buildScenes = SceneHelper.GetScenesInBuild();\n// Returns only scenes in Build Settings\n#endif\nLoad scene, extract data, auto-unload:
C#using WallstopStudios.UnityHelpers.Core.Helper;\n\n// RAII pattern - scene unloaded when disposed\nusing (var scope = SceneHelper.GetObjectOfTypeInScene<LevelConfig>(\"Scenes/LevelData\"))\n{\n if (scope.HasObject)\n {\n LevelConfig config = scope.Object;\n // Use config data\n }\n // Scene automatically unloaded here\n}\nUse for:
The problem: Unity's == operator overload can be slow, and destroyed UnityEngine.Objects return true for == null but false for is null.
using WallstopStudios.UnityHelpers.Core.Helper;\n\nGameObject obj = GetMaybeDestroyedObject();\n\n// Proper Unity null check\nbool isNull = Objects.Null(obj);\nbool notNull = Objects.NotNull(obj);\nHandles:
Combine hash codes correctly:
C#using WallstopStudios.UnityHelpers.Core.Helper;\n\npublic class CompositeKey\n{\n public string Name;\n public int Level;\n public Vector2 Position;\n\n public override int GetHashCode()\n {\n // FNV-1a based hash combination\n return Objects.HashCode(Name, Level, Position);\n }\n}\nSupports up to 11 parameters. Uses FNV-1a algorithm for good distribution.
Hash entire collections:
C#List<int> numbers = new List<int> { 1, 2, 3, 4, 5 };\nint hash = Objects.EnumerableHashCode(numbers);\nUse for:
Human-readable byte counts:
C#using WallstopStudios.UnityHelpers.Core.Helper;\n\nlong bytes = 1536000;\nstring formatted = FormattingHelpers.FormatBytes(bytes);\n// Result: \"1.46 MB\"\nAuto-scales to B, KB, MB, GB, TB.
Use for:
Enumerate 2D/3D array indices:
C#using WallstopStudios.UnityHelpers.Core.Helper;\n\nint[,] grid = new int[10, 10];\n\n// Get all indices as tuples\nforeach (var (x, y) in IterationHelpers.IndexOver(grid))\n{\n grid[x, y] = x + y;\n}\n\n// Buffered (reduces allocations)\nusing (var buffer = Buffers<(int, int)>.List.Get())\n{\n IterationHelpers.IndexOver(grid, buffer.Value);\n foreach (var (x, y) in buffer.Value)\n {\n // Process\n }\n}\nAlso supports 3D arrays with (int, int, int) tuples.
Marshalling between int[] and byte[]:
C#using WallstopStudios.UnityHelpers.Core.Helper;\n\nint[] ints = { 1, 2, 3, 4, 5 };\n\n// Convert to bytes (uses Buffer.BlockCopy)\nbyte[] bytes = ArrayConverter.IntArrayToByteArrayBlockCopy(ints);\n\n// Convert back\nint[] restored = ArrayConverter.ByteArrayToIntArrayBlockCopy(bytes);\nUse for:
Performance: Uses native memory copy (Buffer.BlockCopy) which is faster than element-by-element loops due to optimized native implementation, though both are O(n).
"},{"location":"features/utilities/helper-utilities/#custom-comparers","title":"Custom Comparers","text":"Create IComparer from lambda:
C#using WallstopStudios.UnityHelpers.Core.Helper;\n\nvar enemies = new List<Enemy>();\n\n// Sort by health descending\nenemies.Sort(new FuncBasedComparer<Enemy>((a, b) =>\n b.health.CompareTo(a.health) // Descending\n));\nReverse any comparer:
C#var comparer = Comparer<int>.Default;\nvar reversed = new ReverseComparer<int>(comparer);\n\n// Now sorts descending\nlist.Sort(reversed);\nDetect if running in a CI environment:
C#using WallstopStudios.UnityHelpers.Core.Helper;\n\nif (Helpers.IsRunningInContinuousIntegration)\n{\n // Skip interactive dialogs, use defaults\n}\n\nif (Helpers.IsRunningInBatchMode)\n{\n // Running headless (no graphics device)\n}\nSupported CI systems (checked via environment variables):
CI System Environment Variable Generic CICI GitHub Actions GITHUB_ACTIONS GitLab CI GITLAB_CI Jenkins JENKINS_URL Travis CI TRAVIS CircleCI CIRCLECI Azure Pipelines TF_BUILD TeamCity TEAMCITY_VERSION Buildkite BUILDKITE AWS CodeBuild CODEBUILD_BUILD_ID Bitbucket Pipelines BITBUCKET_BUILD_NUMBER AppVeyor APPVEYOR Drone CI DRONE Unity CI UNITY_CI Unity Tests UNITY_TESTS Check specific environment variables:
C#using WallstopStudios.UnityHelpers.Core.Helper;\n\n// Check if a specific environment variable is set (non-empty, non-whitespace)\nbool onGitHub = Helpers.IsEnvironmentVariableSet(\n Helpers.CiEnvironmentVariables.GitHubActions\n);\n\nbool onJenkins = Helpers.IsEnvironmentVariableSet(\n Helpers.CiEnvironmentVariables.JenkinsUrl\n);\n\n// Access all known CI variable names\nforeach (string varName in Helpers.CiEnvironmentVariables.All)\n{\n if (Helpers.IsEnvironmentVariableSet(varName))\n {\n Debug.Log($\"CI detected via: {varName}\");\n }\n}\nUse for:
Helpers.Find<T>() caches, but don't call every frame anywayIterateOverAllChildrenRecursively with buffers for hot paths#if UNITY_EDITOR guards for editor-only helpersusing WallstopStudios.UnityHelpers.Core.Helper; at top of fileThis guide summarizes the math primitives and extension helpers in this package and shows how to apply them effectively, with examples, performance notes, and practical scenarios.
Contents
PositiveMod to ensure non-negative modulo results for indices and cyclic counters.WrappedAdd/WrappedIncrement for ring buffer indexes and cursor navigation.Example:
C#using WallstopStudios.UnityHelpers.Core.Helper;\n\nint i = -1;\ni = i.PositiveMod(5); // 4\ni = i.WrappedAdd(2, 5); // 1\n\nfloat angle = -30f;\nfloat normalized = angle.PositiveMod(360f); // 330f\nDiagram (wrap-around on a ring of size 5):
Text OnlyIndex: 0 1 2 3 4\n \u2196 \u2199\n \\ +2 from 4 => 1\n\nStart at 4, add 2 \u2192 6 \u2192 6 % 5 = 1\nfloat.Approximately(rhs, tolerance) and double.Approximately add a magnitude-scaled fudge factor.Example:
C#bool close = 0.1f.Approximately(0.10001f, 0.0001f); // true\nClampClamp<T>(min, max) works for any IComparable<T>.Why it exists: Provides 2D line segment math for collision detection, ray-casting, and geometric queries.
When to use:
When NOT to use:
Example:
C#using WallstopStudios.UnityHelpers.Core.Math;\nvar a = new Line2D(new Vector2(0,0), new Vector2(2,0));\nvar b = new Line2D(new Vector2(1,-1), new Vector2(1,1));\nbool hit = a.Intersects(b); // true\nDiagram (segment intersection):
Text Onlyy\u2191 b.to (1,1)\n | \u2502\n | \u2502 b\n | a \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25b6 x\n | (1,0)\u00d7 \u2190 intersection\n | \u2502\n | \u2502\n +\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n b.from (1,-1)\nGetting the exact intersection point:
C#var wall = new Line2D(new Vector2(0, 0), new Vector2(10, 0));\nvar ray = new Line2D(playerPos, targetPos);\n\nif (wall.TryGetIntersectionPoint(ray, out Vector2 hitPoint))\n{\n // Spawn bullet impact effect at exact hitPoint\n Instantiate(sparksPrefab, hitPoint, Quaternion.identity);\n}\nCircle intersection (bullets hitting circular enemies):
C#var bulletPath = new Line2D(bulletStart, bulletEnd);\nvar enemy = new Circle(enemyPosition, enemyRadius);\n\nif (bulletPath.Intersects(enemy))\n{\n // Bullet hit the enemy\n enemy.TakeDamage(bulletDamage);\n}\nClosest point on line (snapping to paths):
C#var path = new Line2D(pathStart, pathEnd);\nVector2 snappedPosition = path.ClosestPointOnLine(mouseWorldPos);\n// Use for UI snapping, path following, or grid alignment\nPerformance tip: Use DistanceSquaredToPoint instead of DistanceToPoint when comparing distances (avoids expensive square root):
// Fast distance comparison (no sqrt)\nfloat distSq = line.DistanceSquaredToPoint(point);\nif (distSq < thresholdSquared)\n{\n // Point is within threshold\n}\nWhy it exists: Extends Line2D concepts to 3D space for sphere intersection, bounding box clipping, and skew line distance.
When to use:
When NOT to use:
Basic operations:
C#using WallstopStudios.UnityHelpers.Core.Math;\n\nvar ray = new Line3D(gunBarrel.position, hitPoint);\nvar enemyBounds = new BoundingBox3D(enemy.bounds);\n\n// Check if ray hits enemy bounding box\nif (ray.Intersects(enemyBounds))\n{\n enemy.TakeDamage(bulletDamage);\n}\nClosest points between two 3D lines (skew lines):
Problem: In 3D, two lines might not actually intersect (imagine two pipes that pass by each other). This finds the closest approach.
C#var ropeA = new Line3D(ropeAStart, ropeAEnd);\nvar ropeB = new Line3D(ropeBStart, ropeBEnd);\n\nif (ropeA.TryGetClosestPoints(ropeB, out Vector3 pointOnA, out Vector3 pointOnB))\n{\n float separation = Vector3.Distance(pointOnA, pointOnB);\n if (separation < 0.1f)\n {\n // Ropes are touching or tangled\n }\n}\nSphere intersection (force fields, explosions):
C#var laserBeam = new Line3D(laserStart, laserEnd);\nvar shield = new Sphere(shieldCenter, shieldRadius);\n\nif (laserBeam.Intersects(shield))\n{\n float distance = laserBeam.DistanceToSphere(shield);\n // distance == 0 means line passes through sphere\n // distance > 0 means line misses sphere\n}\nWhy it exists: Solves the \"is this value in a valid range\" problem with clear, readable code and support for different boundary conditions.
When to use:
When NOT to use:
if (x >= min && x <= max))Example:
C#using WallstopStudios.UnityHelpers.Core.Math;\nvar r = Range<int>.Inclusive(0, 10);\nbool inside = r.Contains(10); // true (10 is included)\nChoosing the right inclusivity:
C#// [0, 10] - both endpoints included (closed interval)\nvar healthRange = Range<int>.Inclusive(0, 10);\nhealthRange.Contains(0); // true\nhealthRange.Contains(10); // true\n\n// [0, 10) - start included, end excluded (common for indices)\nvar arrayRange = Range<int>.InclusiveExclusive(0, 10);\narrayRange.Contains(0); // true\narrayRange.Contains(10); // false (typical for array[0..10))\n\n// (0, 1) - neither endpoint included (open interval)\nvar normalized = Range<float>.Exclusive(0f, 1f);\nnormalized.Contains(0f); // false\nnormalized.Contains(0.5f); // true\nnormalized.Contains(1f); // false\nOverlap detection:
C#var morningShift = Range<int>.Inclusive(9, 13); // 9am-1pm\nvar afternoonShift = Range<int>.Inclusive(13, 17); // 1pm-5pm\n\nbool conflict = morningShift.Overlaps(afternoonShift); // true (overlap at 1pm)\nDate ranges:
C#var january = Range<DateTime>.Inclusive(\n new DateTime(2025, 1, 1),\n new DateTime(2025, 1, 31)\n);\n\nif (january.Contains(someDate))\n{\n // Event happened in January\n}\nWhy it exists: Provides parabolic math for projectile motion, jump arcs, and smooth animation curves without writing quadratic equations by hand.
When to use:
When NOT to use:
Example:
C#using WallstopStudios.UnityHelpers.Core.Math;\n\nvar p = new Parabola(maxHeight: 5f, length: 10f);\nif (p.TryGetValueAtNormalized(0.5f, out float y))\n{\n // y == 5 (at the peak)\n}\nDiagram (normalized parabola):
Text Onlyy\u2191 * vertex (0.5, 5)\n | *\n | *\n | *\n | *\n |* *\n +\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500*\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25b6 x (t from 0..1)\n 0 0.5 1\nCustom coefficients (when you have a specific equation):
C#// Create parabola from equation y = -0.5x\u00b2 + 5x\nvar p = Parabola.FromCoefficients(a: -0.5f, b: 5f, length: 10f);\nPerformance tip: Use GetValueAtUnchecked when you know the input is in range (skips bounds checking):
// In a tight loop updating many projectiles\nfor (int i = 0; i < projectiles.Length; i++)\n{\n float x = projectiles[i].distanceTraveled;\n if (x >= 0 && x <= parabola.Length)\n {\n float y = parabola.GetValueAtUnchecked(x); // No bounds check\n projectiles[i].position.y = y;\n }\n}\nNormalized vs Absolute coordinates:
C#// Normalized: Use when working with 0-1 interpolation (animations)\nfloat t = animationTime / totalDuration; // 0-1\nparabola.TryGetValueAtNormalized(t, out float y);\n\n// Absolute: Use when working with world-space coordinates\nfloat worldX = transform.position.x;\nparabola.TryGetValueAt(worldX, out float worldY);\nWhy it exists: Detects whether a point lies inside an irregular polygon, solving the \"did the player click this shape\" problem.
When to use:
When NOT to use:
Vector2.Distance(point, center) <= radius)Rect.Contains)Important: This uses the ray-casting algorithm \u2014 it counts how many times a ray from the point crosses polygon edges. Odd count = inside, even count = outside.
2D polygon test:
C#using WallstopStudios.UnityHelpers.Core.Math;\n\nVector2[] zoneShape = new Vector2[]\n{\n new(0, 0), new(10, 0), new(10, 5), new(5, 10), new(0, 5)\n};\n\nVector2 clickPos = Camera.main.ScreenToWorldPoint(Input.mousePosition);\n\nif (PointPolygonCheck.IsPointInsidePolygon(clickPos, zoneShape))\n{\n Debug.Log(\"Clicked inside the zone!\");\n}\n3D polygon with plane projection:
C#// Test if 3D point is inside a 3D triangle (projects onto plane)\nVector3[] triangleFace = new Vector3[]\n{\n new(0, 0, 0), new(5, 0, 0), new(2.5f, 5, 0)\n};\nVector3 faceNormal = Vector3.forward; // Must be normalized\n\nVector3 testPoint = new Vector3(2.5f, 2f, 1f); // Will project onto z=0 plane\n\nif (PointPolygonCheck.IsPointInsidePolygon(testPoint, triangleFace, faceNormal))\n{\n Debug.Log(\"Point projects inside triangle\");\n}\nZero-allocation version for hot paths:
C#// Use ReadOnlySpan to avoid heap allocations\nSpan<Vector2> vertices = stackalloc Vector2[4]\n{\n new(0, 0), new(1, 0), new(1, 1), new(0, 1)\n};\n\nbool inside = PointPolygonCheck.IsPointInsidePolygon(clickPos, vertices);\n// No GC allocations when using ReadOnlySpan\nEdge cases to know:
Simplify (float epsilon) and SimplifyPrecise (double tolerance) reduce vertex count while preserving shape.Example:
C#using WallstopStudios.UnityHelpers.Core.Helper;\nList<Vector2> simplified = LineHelper.Simplify(points, epsilon: 0.1f);\nDiagram (original vs simplified):
Text OnlyOriginal: *----*--*---*--*-----*\nSimplified: *-----------*--------*\n\nFewer vertices within epsilon of the original polyline.\nVisual:
Convex hull (monotone chain / Jarvis examples used by helpers):
Text OnlyPoints: \u00b7 \u00b7 \u00b7\n \u00b7 \u00b7 \u00b7\n \u00b7 \u00b7\n\nHull: \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n \u2502 \u2502\n \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2518\n \u2514\u2500\u2510\nVisual:
Edge Cases Gallery
","text":""},{"location":"features/utilities/math-and-extensions/#unity-extensions","title":"Unity Extensions","text":"OrthographicBoundsExample:
C#Rect r = rectTransform.GetWorldRect();\nBounds view = Camera.main.OrthographicBounds();\nDiagrams:
\u2022 corner \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n \u2572 \u2502 AABB (r) \u2502\n \u2572 rotated \u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n \u2572 rectangle \u2502 \u2571\u2502 UI \u2571\u2502 \u2502\n \u2022 \u2502 \u2571 \u2514\u2500\u2500\u2500\u2500\u2571\u2500\u2518 \u2502\n \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 view (Bounds) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n \u2502 height=2*size \u2502\n \u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n near \u2500\u2500\u2500\u25b6\u2502 \u2502 camera FOV \u2502 \u2502\u25c0\u2500\u2500 far\n \u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\n \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\nExample:
C#using WallstopStudios.UnityHelpers.Core.Extension;\nColor avg = sprite.GetAverageColor(ColorAveragingMethod.LAB);\nstring html = avg.ToHex();\nDominant color example (bucket-based):
C#// Emphasize palette extraction (posterized sprites, UI swatches)\nvar dominant = pixels.GetAverageColor(ColorAveragingMethod.Dominant, alphaCutoff: 0.05f);\nDiagram (dominant buckets):
Text OnlyRGB space buckets \u2192 counts\n [R][G][B] \u2026 [R+\u0394][G][B] \u2026 [R][G+\u0394][B] \u2026\n \u2191 pick max bucket centroid as dominant\nInfinite cycling:
C#using WallstopStudios.UnityHelpers.Core.Extension;\n\n// Cycle through elements endlessly for repeating patterns\nvar colors = new[] { Color.red, Color.blue, Color.green };\nforeach (var color in colors.Infinite())\n{\n // Loops forever: red, blue, green, red, blue, green...\n if (shouldStop) break;\n}\nPartition into chunks:
C#// Split large collections into fixed-size batches\nvar items = Enumerable.Range(0, 100);\nforeach (var batch in items.Partition(10))\n{\n // Process 10 items at a time\n ProcessBatch(batch); // batch is a List<int> of size 10\n}\n\n// Zero-allocation version for hot paths\nusing (var batchBuffer = items.PartitionPooled(10))\n{\n foreach (var batch in batchBuffer)\n {\n // batch is reused from pool, no allocations\n }\n} // Automatically returns buffer to pool\nShuffled (non-destructive):
C#// Get shuffled copy without modifying original\nvar shuffled = items.Shuffled();\n// Original list unchanged\nRemove O(1) by swapping with last element:
C#// Fast removal when order doesn't matter (particle systems, entity lists)\nList<Enemy> enemies = GetActiveEnemies();\nenemies.RemoveAtSwapBack(3); // Swaps enemy[3] with last enemy, then removes\n// Avoids O(n) shift operation of List.RemoveAt by swapping with last element\nPartition (split by predicate):
C#var numbers = new List<int> { 1, 2, 3, 4, 5, 6 };\nvar (evens, odds) = numbers.Partition(n => n % 2 == 0);\n// evens: [2, 4, 6]\n// odds: [1, 3, 5]\nCustom sorting:
C#// GhostSort: Hybrid sort algorithm for medium-sized lists\nlargeList.GhostSort(); // Uses IComparable<T>\n\n// Custom comparison function\nlist.Sort((a, b) => a.priority.CompareTo(b.priority));\nThread-safe get-or-create:
C#using WallstopStudios.UnityHelpers.Core.Extension;\n\n// Thread-safe for ConcurrentDictionary\nvar value = dict.GetOrAdd(key, () => new ExpensiveObject());\n\n// Read-only version (doesn't modify dict)\nvar value = readOnlyDict.GetOrElse(key, defaultValue);\nMerge dictionaries:
C#var defaults = new Dictionary<string, int> { [\"health\"] = 100, [\"mana\"] = 50 };\nvar overrides = new Dictionary<string, int> { [\"health\"] = 150 };\n\nvar merged = defaults.Merge(overrides);\n// Result: { [\"health\"] = 150, [\"mana\"] = 50 }\nDeep equality:
C#// Compare dictionary contents (not just references)\nbool same = dict1.ContentEquals(dict2); // Compares all key-value pairs\nBounds from points example:
C#using WallstopStudios.UnityHelpers.Core.Extension;\n\n// Compute BoundsInt for occupied grid cells\nVector3Int[] positions = GetOccupiedCells();\nBoundsInt? area = positions.GetBounds(inclusive: false);\nif (area is BoundsInt b)\n{\n // b contains all positions\n}\nBounds aggregation example:
C#// Merge many Bounds (e.g., from Renderers)\nRenderer[] renderers = GetComponentsInChildren<Renderer>();\nBounds? merged = renderers.Select(r => r.bounds).GetBounds();\nif (merged is Bounds totalBounds)\n{\n // totalBounds encompasses all renderers\n}\nWhy it exists: Automatically convert between common programming case styles without writing regex or manual parsing.
C#using WallstopStudios.UnityHelpers.Core.Extension;\n\nstring input = \"XMLHttpRequest\";\n\ninput.ToPascalCase(); // \"XmlHttpRequest\"\ninput.ToCamelCase(); // \"xmlHttpRequest\"\ninput.ToSnakeCase(); // \"xml_http_request\"\ninput.ToKebabCase(); // \"xml-http-request\"\ninput.ToTitleCase(); // \"Xml Http Request\"\nSmart tokenization handles mixed cases intelligently.
","text":""},{"location":"features/utilities/math-and-extensions/#string-utilities","title":"String UtilitiesLevenshtein Distance (edit distance):
C#// Calculate how many edits to transform one string into another\nstring a = \"kitten\";\nstring b = \"sitting\";\nint distance = a.LevenshteinDistance(b); // 3 edits\n// Use for: fuzzy matching, spell correction, search suggestions\nBase64 encoding:
C#string text = \"Hello, World!\";\nstring encoded = text.ToBase64(); // \"SGVsbG8sIFdvcmxkIQ==\"\nstring decoded = encoded.FromBase64(); // \"Hello, World!\"\nString analysis:
C#bool isNum = \"12345\".IsNumeric(); // true\nbool isAlpha = \"Hello\".IsAlphabetic(); // true\nbool isAlphaNum = \"Hello123\".IsAlphanumeric(); // true\nTruncate with ellipsis:
C#string long = \"This is a very long string\";\nstring short = long.Truncate(10); // \"This is a...\"\n// UTF-8 conversions\nbyte[] bytes = \"Hello\".GetBytes();\nstring text = bytes.GetString();\nExample:
C#using WallstopStudios.UnityHelpers.Core.Extension;\nVector2Int v = Direction.NorthWest.AsVector2Int(); // (-1, 1)\nWhy it exists: Standard C# enum operations cause boxing allocations and are slow in hot paths. These helpers solve performance problems.
"},{"location":"features/utilities/math-and-extensions/#zero-allocation-flag-checking","title":"Zero-Allocation Flag CheckingThe problem: Standard HasFlag() boxes both enums, causing GC pressure.
using WallstopStudios.UnityHelpers.Core.Extension;\n\n[Flags]\npublic enum Permissions\n{\n None = 0,\n Read = 1,\n Write = 2,\n Execute = 4\n}\n\nPermissions userPerms = Permissions.Read | Permissions.Write;\n\n// \u274c BAD: Causes boxing allocations\nif (userPerms.HasFlag(Permissions.Write)) { }\n\n// \u2705 GOOD: Zero allocations\nif (userPerms.HasFlagNoAlloc(Permissions.Write)) { }\nUse HasFlagNoAlloc in:
The problem: enum.ToString() is slow (reflection) and allocates every call.
public enum GameState { MainMenu, Playing, Paused, GameOver }\n\nGameState state = GameState.Playing;\n\n// \u274c SLOW: Uses reflection every time\nstring name = state.ToString();\n\n// \u2705 FAST: Cached in array/dictionary after first call\nstring cached = state.ToCachedName();\n// Subsequent calls are O(1) lookups with zero allocation\nPerformance: ToCachedName uses cached lookups to avoid repeated allocations and string conversions after the first call.
","text":""},{"location":"features/utilities/math-and-extensions/#display-names-for-ui","title":"Display Names for UIThe problem: Enum values often need different names in UI than in code.
C#using WallstopStudios.UnityHelpers.Core.Attribute;\n\npublic enum Difficulty\n{\n [EnumDisplayName(\"Easy Mode\")]\n Easy,\n\n [EnumDisplayName(\"Normal\")]\n Medium,\n\n [EnumDisplayName(\"NIGHTMARE MODE!!!\")]\n Hard\n}\n\nDifficulty current = Difficulty.Hard;\nstring displayName = current.ToDisplayName(); // \"NIGHTMARE MODE!!!\"\n// Falls back to enum name if attribute not present\nUse for:
Why it exists: Unity's Random class is limited and not suitable for all scenarios. These extensions provide additional random generation capabilities.
The problem: Selecting items based on probability weights (loot tables, spawn chances).
C#using WallstopStudios.UnityHelpers.Core.Extension;\n\n// Items with different drop chances\nvar loot = new[]\n{\n (item: \"Common Sword\", weight: 50),\n (item: \"Rare Shield\", weight: 30),\n (item: \"Epic Helmet\", weight: 15),\n (item: \"Legendary Ring\", weight: 5)\n};\n\nIRandom rng = PRNG.Instance;\nstring drop = rng.NextWeighted(loot); // More likely to get Common Sword\n\n// Get index instead of value\nint dropIndex = rng.NextWeightedIndex(loot.Select(x => x.weight));\nUniform random vectors:
C#// Random point in rectangle\nVector2 point = rng.NextVector2(minX, maxX, minY, maxY);\n\n// Random point inside circle\nVector2 inCircle = rng.NextVector2InRange(radius);\n\n// Random point ON sphere surface (uniform distribution)\nVector3 onSphere = rng.NextVector3OnSphere(radius);\n// Uses Marsaglia's method for true uniform distribution\n\n// Random rotation (uniform distribution)\nQuaternion rotation = rng.NextQuaternion();\n// Uses Shoemake's algorithm\n// Random opaque color\nColor color = rng.NextColor();\n\n// Random color in HSV range (for similar hues)\nColor tint = rng.NextColorInRange(\n baseColor: Color.red,\n hueVariance: 0.1f,\n saturationVariance: 0.2f,\n valueVariance: 0.2f\n);\nReservoir sampling \u2014 Pick k random items from a large collection without loading it all into memory:
C#// Select 5 random enemies from potentially huge list\nIEnumerable<Enemy> allEnemies = GetAllEnemiesInWorld();\nList<Enemy> randomFive = rng.NextSubset(allEnemies, k: 5);\n// O(n) time, uses reservoir sampling for uniform probability\nbool coinFlip = rng.NextBool(); // 50/50\nbool biasedFlip = rng.NextBool(0.7f); // 70% true\nint sign = rng.NextSign(); // Randomly -1 or +1\nWhy it exists: Unity's AsyncOperation and coroutines don't natively support modern async/await patterns. This bridges the gap.
The problem: Unity's AsyncOperations (scene loading, asset loading) don't support await.
using WallstopStudios.UnityHelpers.Core.Extension;\nusing UnityEngine.SceneManagement;\n\n// \u2705 Now you can await scene loading\nasync Task LoadGameScene()\n{\n var operation = SceneManager.LoadSceneAsync(\"GameLevel\");\n await operation;\n\n Debug.Log(\"Scene loaded!\");\n}\nNote: Unity 2023.1+ has built-in await support, but this works in older versions.
","text":""},{"location":"features/utilities/math-and-extensions/#convert-asyncoperation-to-task","title":"Convert AsyncOperation to Task C#// As Task\nTask task = asyncOperation.AsTask();\nawait task;\n\n// As ValueTask (reduces allocations for short operations)\nValueTask valueTask = asyncOperation.AsValueTask();\nawait valueTask;\nThe problem: You have async/await code (from a library, or your own), but need to run it in a Unity coroutine context.
C#using WallstopStudios.UnityHelpers.Core.Extension;\n\nasync Task<string> DownloadDataAsync()\n{\n // Some async operation (HttpClient, database, etc.)\n await Task.Delay(1000);\n return \"Downloaded data\";\n}\n\n// In MonoBehaviour\nIEnumerator Start()\n{\n // \u2705 Convert Task to IEnumerator\n return DownloadDataAsync().AsCoroutine();\n}\n// Chain operations on ValueTask\nawait myValueTask.WithContinuation(() => Debug.Log(\"Done!\"));\nWhen to use:
When NOT to use:
PositiveMod instead of % for indices and angles when negatives are possible.SimplifyPrecise for offline tooling; use Simplify during gameplay for speed.RectTransform, Camera, Grid) on the main thread.The intelligent pooling system provides automatic memory management for WallstopGenericPool<T> instances. Instead of pools growing unbounded or requiring manual purge calls, the system:
flowchart TB\n subgraph \"Intelligent Purging Flow\"\n Access[Pool Access] --> Track[Track Usage]\n Track --> Check{Purge Trigger?}\n Check -->|Yes| Eligible{Items Eligible?}\n Eligible -->|Idle Timeout Exceeded| Purge[Purge Items]\n Eligible -->|No| Skip[Skip Purge]\n Purge --> Limit{Max Purges/Op?}\n Limit -->|Reached| Pending[Mark Pending]\n Limit -->|Not Reached| Continue[Continue]\n endBy default, intelligent purging is enabled with conservative settings:
C#using WallstopStudios.UnityHelpers.Utils;\n\n// Pools automatically use intelligent purging\nvar pool = new WallstopGenericPool<List<int>>(\n createFunc: () => new List<int>(),\n actionOnGet: list => list.Clear()\n);\n\n// Rent and return as usual - purging happens automatically\nvar list = pool.Get();\nlist.Add(1);\nlist.Add(2);\npool.Release(list);\n// Disable all intelligent purging\nPoolPurgeSettings.DisableGlobally();\nusing WallstopStudios.UnityHelpers.Utils;\n\n// Configure specific type behavior\nPoolPurgeSettings.Configure<ExpensiveObject>(options =>\n{\n options.IdleTimeoutSeconds = 600f; // 10 minutes\n options.MinRetainCount = 5; // Always keep 5\n options.WarmRetainCount = 10; // Keep 10 when active\n});\n\n// Configure all List<T> variants\nPoolPurgeSettings.ConfigureGeneric(typeof(List<>), options =>\n{\n options.IdleTimeoutSeconds = 120f; // 2 minutes\n options.BufferMultiplier = 1.5f; // 50% buffer\n});\n\n// Disable purging for specific types\nPoolPurgeSettings.Disable<CriticalResource>();\nPoolOptions<T> provides per-pool configuration:
using WallstopStudios.UnityHelpers.Utils;\n\nvar options = new PoolOptions<MyObject>\n{\n // Size limits\n MaxPoolSize = 100, // Hard cap on pool size\n MinRetainCount = 0, // Absolute minimum to keep\n WarmRetainCount = 2, // Keep 2 when active\n\n // Timing\n IdleTimeoutSeconds = 300f, // 5 minutes before eligible\n PurgeIntervalSeconds = 60f, // Periodic check interval\n\n // Intelligent purging\n UseIntelligentPurging = true,\n BufferMultiplier = 2.0f, // 2x peak usage buffer\n RollingWindowSeconds = 300f, // 5 minute window\n HysteresisSeconds = 120f, // 2 minute spike cooldown\n SpikeThresholdMultiplier = 2.5f, // 2.5x average = spike\n MaxPurgesPerOperation = 10, // Spread large purges\n\n // Triggers\n Triggers = PurgeTrigger.OnRent | PurgeTrigger.OnReturn,\n\n // Callbacks\n OnPurge = (item, reason) => Debug.Log($\"Purged: {reason}\")\n};\n\nvar pool = new WallstopGenericPool<MyObject>(\n createFunc: () => new MyObject(),\n options: options\n);\nOnRent Check when item is rented (lazy cleanup) OnReturn Check when item is returned Periodic Timer-based checks at PurgeIntervalSeconds Explicit Only purge when Purge() is called manually"},{"location":"features/utilities/pooling-guide/#purgereason-values","title":"PurgeReason Values","text":"Reason Description IdleTimeout Item was idle longer than IdleTimeoutSeconds CapacityExceeded Pool exceeded MaxPoolSize MemoryPressure System memory pressure detected AppBackgrounded Application went to background SceneUnloaded Scene was unloaded Explicit Manual Purge() call BudgetExceeded Global pool budget exceeded"},{"location":"features/utilities/pooling-guide/#global-settings-poolpurgesettings","title":"Global Settings (PoolPurgeSettings)","text":"Configure system-wide defaults:
C#using WallstopStudios.UnityHelpers.Utils;\n\n// Enable/disable globally\nPoolPurgeSettings.GlobalEnabled = true;\n\n// Configure defaults\nPoolPurgeSettings.DefaultGlobalIdleTimeoutSeconds = 300f;\nPoolPurgeSettings.DefaultGlobalMinRetainCount = 0;\nPoolPurgeSettings.DefaultGlobalWarmRetainCount = 2;\nPoolPurgeSettings.DefaultGlobalBufferMultiplier = 2.0f;\nPoolPurgeSettings.DefaultGlobalRollingWindowSeconds = 300f;\nPoolPurgeSettings.DefaultGlobalHysteresisSeconds = 120f;\nPoolPurgeSettings.DefaultGlobalSpikeThresholdMultiplier = 2.5f;\nPoolPurgeSettings.DefaultGlobalMaxPurgesPerOperation = 10;\n\n// Lifecycle hooks\nPoolPurgeSettings.PurgeOnLowMemory = true; // Application.lowMemory\nPoolPurgeSettings.PurgeOnAppBackground = true; // Application.focusChanged\nPoolPurgeSettings.PurgeOnSceneUnload = true; // SceneManager.sceneUnloaded\nThe system uses a two-tier retention model:
Effective Floor = max(MinRetainCount, isActive ? WarmRetainCount : 0)\nExample:
MinRetainCount = 0, WarmRetainCount = 2The \"comfortable size\" determines when purging is needed:
Text OnlyComfortableSize = max(EffectiveMinRetain, RollingHighWaterMark * BufferMultiplier)\nItems that have been idle longer than IdleTimeoutSeconds are purged regardless of comfortable size. The comfortable size primarily influences the target retention during non-idle purges and memory pressure events.
After a usage spike, purging is suppressed for HysteresisSeconds to prevent purge-allocate cycles:
sequenceDiagram\n participant App as Application\n participant Pool as Pool\n\n Note over App,Pool: Normal usage period\n App->>Pool: Get items (low volume)\n Pool->>Pool: Track high-water mark\n\n Note over App,Pool: Usage spike detected\n App->>Pool: Get many items rapidly\n Pool->>Pool: Spike! Start hysteresis\n\n Note over App,Pool: Hysteresis period (2 min default)\n Pool->>Pool: Purging suppressed\n\n Note over App,Pool: After hysteresis\n Pool->>Pool: Resume normal purgingLarge purge operations are spread across multiple calls:
C#// Configure max items purged per operation\noptions.MaxPurgesPerOperation = 10;\n\n// Pool tracks pending purges\nif (pool.HasPendingPurges)\n{\n // More items to purge on next trigger\n}\n\n// Force immediate full purge (bypasses limit)\npool.ForceFullPurge();\nThe system monitors memory pressure and adjusts purging aggressiveness:
C#using WallstopStudios.UnityHelpers.Utils;\n\n// Check current pressure level\nMemoryPressureLevel level = MemoryPressureMonitor.CurrentPressure;\n\nswitch (level)\n{\n case MemoryPressureLevel.None:\n // Normal operation\n break;\n case MemoryPressureLevel.Low:\n // Minor pressure, slightly more aggressive\n break;\n case MemoryPressureLevel.Medium:\n // Moderate pressure, reduced buffers\n break;\n case MemoryPressureLevel.High:\n // Significant pressure, aggressive purging\n break;\n case MemoryPressureLevel.Critical:\n // Emergency cleanup, bypass limits\n break;\n}\nLarge objects (allocated on the Large Object Heap) get stricter policies:
C#using WallstopStudios.UnityHelpers.Utils;\n\n// Enable size-aware policies\nPoolPurgeSettings.SizeAwarePoliciesEnabled = true;\n\n// Configure thresholds\nPoolPurgeSettings.LargeObjectThresholdBytes = 85000; // .NET LOH threshold\nPoolPurgeSettings.LargeObjectBufferMultiplier = 1.0f; // No buffer (vs 2.0x)\nPoolPurgeSettings.LargeObjectIdleTimeoutMultiplier = 0.5f; // 50% shorter\nPoolPurgeSettings.LargeObjectWarmRetainCount = 1; // Keep 1 (vs 2)\nEstimate object sizes for policy decisions:
C#using WallstopStudios.UnityHelpers.Utils;\n\n// Estimate single item size\nlong size = PoolSizeEstimator.EstimateItemSizeBytes<MyLargeObject>();\n\n// Estimate array size\nlong arraySize = PoolSizeEstimator.EstimateArraySizeBytes<byte>(length: 100000);\n\n// Check if on LOH\nbool isLargeObject = size >= PoolPurgeSettings.LargeObjectThresholdBytes;\nPools track access patterns for intelligent decisions:
C#using WallstopStudios.UnityHelpers.Utils;\n\n// Get frequency statistics\nPoolFrequencyStatistics stats = pool.FrequencyStatistics;\n\n// Access metrics\nfloat rentalsPerMinute = stats.RentalsPerMinute;\nfloat avgInterRentalTime = stats.AverageInterRentalTimeSeconds;\nfloat lastAccess = stats.LastAccessTime;\n\n// Helper properties\nbool isHighFrequency = stats.IsHighFrequency; // > 60 rentals/min\nbool isLowFrequency = stats.IsLowFrequency; // <= 1 rental/min\nbool isUnused = stats.IsUnused; // No recent access\nThe system responds to application lifecycle events:
C#using WallstopStudios.UnityHelpers.Utils;\n\n// Configure lifecycle responses\nPoolPurgeSettings.PurgeOnLowMemory = true; // Application.lowMemory\nPoolPurgeSettings.PurgeOnAppBackground = true; // Application loses focus\nPoolPurgeSettings.PurgeOnSceneUnload = true; // Scene unloaded\nOn mobile platforms:
Track and manage all pools system-wide:
C#using WallstopStudios.UnityHelpers.Utils;\n\n// Configure global budget\nPoolPurgeSettings.GlobalMaxPooledItems = 50000;\n\n// Get global statistics\nGlobalPoolStatistics globalStats = GlobalPoolRegistry.GetStatistics();\nint totalPooled = globalStats.TotalPooledItems;\nfloat budgetUtilization = globalStats.BudgetUtilization;\nint registeredPools = globalStats.RegisteredPoolCount;\n\n// Force budget enforcement\nGlobalPoolRegistry.EnforceBudget();\n\n// Try non-blocking budget check\nif (GlobalPoolRegistry.TryEnforceBudgetIfNeeded())\n{\n // Budget was over, items purged\n}\nWhen the global budget is exceeded, items are evicted across all pools using LRU ordering based on pool access times.
"},{"location":"features/utilities/pooling-guide/#best-practices","title":"Best Practices","text":""},{"location":"features/utilities/pooling-guide/#configuration-hierarchy","title":"Configuration Hierarchy","text":"Settings are resolved in priority order:
PoolPurgeSettings.Configure<T>)PoolPurgeSettings.ConfigureGeneric)[PoolPurgePolicy] on type)// Short-lived temporary collections\nPoolPurgeSettings.Configure<List<int>>(o =>\n{\n o.IdleTimeoutSeconds = 60f;\n o.WarmRetainCount = 5;\n});\n\n// Long-lived expensive objects\nPoolPurgeSettings.Configure<AudioSource>(o =>\n{\n o.IdleTimeoutSeconds = 600f;\n o.MinRetainCount = 2;\n o.WarmRetainCount = 4;\n});\n\n// Large buffers (be aggressive)\nPoolPurgeSettings.Configure<byte[]>(o =>\n{\n o.IdleTimeoutSeconds = 30f;\n o.BufferMultiplier = 1.0f;\n o.WarmRetainCount = 1;\n});\nMaxPurgesPerOperation = 10 prevents GC spikesFrequencyStatistics to tune per-type settings// Log purge events\nvar options = new PoolOptions<MyObject>\n{\n OnPurge = (item, reason) =>\n {\n Debug.Log($\"[Pool] Purged {typeof(MyObject).Name}: {reason}\");\n }\n};\n\n// Check global stats periodically\nvoid OnGUI()\n{\n var stats = GlobalPoolRegistry.Statistics;\n GUILayout.Label($\"Pools: {stats.RegisteredPoolCount}\");\n GUILayout.Label($\"Items: {stats.TotalPooledItems}/{PoolPurgeSettings.GlobalMaxPooledItems}\");\n GUILayout.Label($\"Budget: {stats.BudgetUtilization:P0}\");\n}\nTL;DR: Use PRNG.Instance for 10-15x faster random generation than UnityEngine.Random, with a rich API for vectors, colors, weighted selection, and more.
Unity Helpers provides 15+ high-performance pseudo-random number generators (PRNGs) through a unified IRandom interface. All generators pass standard statistical tests and are optimized for game development workloads.
UnityEngine.Random (see benchmarks)PRNG.Instance (thread-local)using WallstopStudios.UnityHelpers.Core.Random;\n\n// Use the thread-local default (fastest)\nIRandom random = PRNG.Instance;\n\n// Basic generation\nint number = random.Next(0, 100); // [0, 100)\nfloat value = random.NextFloat(); // [0.0, 1.0)\nbool coinFlip = random.NextBool();\nuint bits = random.NextUint();\n\n// Unity vectors\nVector2 point2D = random.NextVector2(-10f, 10f);\n\n// Colors\nColor randomColor = random.NextColor();\n\n// Weighted selection\nstring[] items = { \"Common\", \"Rare\", \"Epic\" };\nfloat[] weights = { 70f, 25f, 5f };\nstring selected = random.NextWeighted(items.Zip(weights, (x, y) => (x, y)));\n\n// Gaussian distribution\nfloat normalValue = random.NextGaussian(mean: 0f, stdDev: 1f);\nPRNG.Instance Thread-local default, excellent quality Procedural generation PcgRandom Reproducible, excellent statistical properties High-throughput effects SplitMix64 Fastest with good quality Cryptographic seeding N/A Use System.Security.Cryptography instead Legacy compatibility UnityRandom Matches UnityEngine.Random behavior"},{"location":"features/utilities/random-generators/#available-generators","title":"Available Generators","text":"All generators implement the IRandom interface:
LinearCongruentialGenerator Fastest Poor Non-critical effects only SplitMix64 Very Fast Very Good High-throughput generation PcgRandom Fast Excellent General purpose, seeded generation IllusionFlow Fast Excellent Balanced speed and quality XoroShiroRandom Fast Very Good Game logic, physics RomuDuo Fast Very Good Alternative to PCG XorShiftRandom Moderate Fair Legacy compatibility WyRandom Moderate Very Good Hash-based scenarios SquirrelRandom Moderate Good Noise-based generation PhotonSpinRandom Slow Excellent Maximum quality needed UnityRandom Slow Fair Match Unity behavior SystemRandom Very Slow Poor .NET compatibility For detailed benchmarks, see Random Performance.
"},{"location":"features/utilities/random-generators/#creating-seeded-generators","title":"Creating Seeded Generators","text":"For reproducible sequences (replays, procedural generation, testing):
C#using WallstopStudios.UnityHelpers.Core.Random;\n\n// Create with specific seed\nPcgRandom seeded = new PcgRandom(seed: 12345);\n\n// Generate reproducible sequence\nfor (int i = 0; i < 10; i++)\n{\n Debug.Log(seeded.Next(0, 100)); // Same values every run\n}\n\n// Different seed = different sequence\nPcgRandom different = new PcgRandom(seed: 67890);\nIRandom random = PRNG.Instance;\n\n// Integers\nint value = random.Next(); // [int.MinValue, int.MaxValue]\nint bounded = random.Next(100); // [0, 100)\nint ranged = random.Next(10, 50); // [10, 50)\n\n// Unsigned integers\nuint bits = random.NextUint();\nuint boundedUint = random.NextUint(1000u);\n\n// Floating point\nfloat f = random.NextFloat(); // [0.0, 1.0)\nfloat rangedF = random.NextFloat(-1f, 1f); // [-1.0, 1.0)\ndouble d = random.NextDouble(); // [0.0, 1.0)\n\n// Boolean\nbool b = random.NextBool(); // 50% true/false\nbool weighted = random.NextBool(0.75f); // 75% true\n// 2D vectors\nVector2 v2 = random.NextVector2(); // Each component [0, 1)\nVector2 ranged2 = random.NextVector2(-10f, 10f); // Each component [-10, 10)\n\n// 3D vectors\nVector3 v3 = random.NextVector3();\nVector3 ranged3 = random.NextVector3(-5f, 5f);\n// Random colors\nColor c = random.NextColor(); // Random RGBA\n// Gaussian (normal) distribution\nfloat gaussian = random.NextGaussian(mean: 0f, stdDev: 1f);\n\n// Weighted selection\nstring[] items = { \"Common\", \"Rare\", \"Epic\", \"Legendary\" };\nfloat[] weights = { 60f, 25f, 12f, 3f };\nstring drop = random.NextWeighted(items.Zip(weights, (x, y) => (x, y)));\n// Shuffle in place\nmyList.Shuffle(random);\n\n// Random element\nT element = random.NextOf(array);\nT element2 = random.NextOf(list);\n\n// Random index\nint index = random.Next(collection.Count);\nPRNG.Instance provides thread-local instances, making it safe for multithreaded code without locks:
// Safe - each thread gets its own instance\nParallel.For(0, 1000, i =>\n{\n int value = PRNG.Instance.Next(0, 100);\n // No race conditions\n});\nFor explicit thread-local control:
C#using WallstopStudios.UnityHelpers.Core.Random;\n\n// Create thread-local wrapper around any generator\nThreadLocalRandom<PcgRandom> threadLocal = new();\nIRandom random = threadLocal.Value; // Per-thread instance\nFor procedural generation, use the seedable Perlin noise generator:
C#using WallstopStudios.UnityHelpers.Core.Random;\n\nPerlinNoise noise = new PerlinNoise(seed: 42);\n\n// 2D noise (terrain, textures)\nfloat value2D = noise.Noise(x, y);\n\n// Octave noise for more detail\nfloat octaves = noise.OctaveNoise(x, y, octaves: 4, persistence: 0.5f);\nPRNG.Instance for most cases \u2014 it's fast, thread-safe, and well-testednew in hot paths \u2014 cache generator instances// \u2705 Good - cache the reference\nprivate IRandom _random = PRNG.Instance;\n\nvoid Update()\n{\n float value = _random.NextFloat();\n}\n\n// \u274c Bad - creates new instance every frame\nvoid Update()\n{\n PcgRandom random = new PcgRandom(); // Allocation!\n float value = random.NextFloat();\n}\nVisual
ReflectionHelpers is a set of utilities for high\u2011performance reflection in Unity projects. It generates and caches delegates to access fields and properties, call methods and constructors, and quickly create common collections \u2014 with safe fallbacks when dynamic IL isn\u2019t available.
Why it exists
What it solves
When to use it
When not to use it
GetValue/SetValue is fine.ReflectionHelpers now partitions cached delegates by capability strategy so that expression, dynamic-IL, and reflection fallbacks never overwrite each other. Key points:
CapabilityKey<TMember> (member metadata + ReflectionDelegateStrategy). This applies to fields, properties, indexers, methods, and constructors (boxed + typed variants).ConditionalWeakTable<Delegate, StrategyHolder> so diagnostics and tests can assert the producing strategy via ReflectionHelpers.TryGetDelegateStrategy.ReflectionHelpers.OverrideReflectionCapabilities(expressions, dynamicIl) temporarily toggles expression/IL support, letting tests (or runtime feature detection) confirm that caches store independent delegates per strategy.ClearFieldGetterCache, ClearPropertyCache, ClearMethodCache, and ClearConstructorCache flush the relevant cache groups to keep unit tests deterministic.GetFieldGetter(FieldInfo), GetFieldSetter(FieldInfo) Emit DynamicMethod IL (BuildFieldGetter/SetterIL) to cast/unbox target and box return CreateCompiled* builds expression delegates; otherwise wraps FieldInfo.GetValue/SetValue FieldGetterCache, FieldSetterCache, static equivalents Supports static + instance fields; struct writes box when IL emit unavailable (IL2CPP/WebGL) Field access (typed) GetFieldGetter<TInstance,TValue>, GetFieldSetter<TInstance,TValue> Emit typed DynamicMethod (setters use by-ref) to avoid boxing Falls back to GetValue/SetValue wrappers; setter fallback boxes then copies back None (callers must hold returned delegate) TInstance must match declaring type; fastest only where IL emit allowed Property access (boxed) GetPropertyGetter(PropertyInfo), GetPropertySetter(PropertyInfo) Emit DynamicMethod (Call/Callvirt) and box value types Expression-compiled wrapper; else PropertyInfo.GetValue/SetValue PropertyGetterCache, PropertySetterCache, static equivalents Handles non-public accessors; fallback reintroduces boxing/allocations Property access (typed) GetPropertyGetter<TInstance,TValue>, GetPropertySetter<TInstance,TValue> Emit typed DynamicMethod with cast/unbox guards Direct reflection wrappers casting to TValue None Avoids boxing only on IL paths; static typed getter limited to static properties Method invokers (boxed) GetMethodInvoker, GetStaticMethodInvoker, InvokeMethod Emit DynamicMethod to unpack object[] args and box return Expression wrappers; otherwise call MethodInfo.Invoke directly MethodInvokers, StaticMethodInvokers Works with private members; fallback incurs reflection cost per call Method invokers (typed static) GetStaticMethodInvoker<\u2026>, GetStaticActionInvoker<\u2026> Emit DynamicMethod per arity (0\u20134) for direct call Try MethodInfo.CreateDelegate; else expression compile TypedStaticInvoker0-4, TypedStaticAction0-4 Signature-checked upfront; limited to four parameters today Method invokers (typed instance) GetInstanceMethodInvoker<TInstance,\u2026>, GetInstanceActionInvoker<TInstance,\u2026> Emit DynamicMethod using ldarga for structs and Callvirt for refs Falls back to Delegate.CreateDelegate / expression lambdas TypedInstanceInvoker0-4, TypedInstanceAction0-4 Requires TInstance assignable to declaring type; fallback boxes structs Constructors & factories GetConstructor, CreateInstance, GetParameterlessConstructor<T>, GetParameterlessConstructor Delegate factory prefers expression lambdas, falls back to dynamic IL newobj and finally reflection (ConstructorInfo.Invoke / Activator.CreateInstance) Reflection invoke (no emit) Constructors, ParameterlessConstructors, TypedParameterlessConstructors Works across Editor/IL2CPP; capability overrides let tests force fallback paths Indexer helpers GetIndexerGetter, GetIndexerSetter Expression lambdas or dynamic IL to handle struct receivers and value conversions Reflection PropertyInfo.Get/SetValue with argument validation IndexerGetters, IndexerSetters Throws IndexOutOfRangeException/InvalidCastException when indices mismatch; respects capability overrides Collection creators CreateArray, GetListCreator(Type), GetDictionaryWithCapacityCreator Emit DynamicMethod for newarr/newobj, plus HashSet.Add wrappers Use Array.CreateInstance, Activator.CreateInstance, or reflection Invoke ArrayCreators, ListCreators, ListWithCapacityCreators, HashSetWithCapacityCreators, adders Create* APIs cache by element type; fallback still functional but allocates Type/attribute scanning GetAllLoadedAssemblies, GetTypesDerivedFrom<T>, HasAttributeSafe Direct reflection with guarded iteration; Editor uses UnityEditor.TypeCache shortcuts Gracefully skips assemblies/types on error; no IL emit needed TypeResolutionCache, FieldLookup, PropertyLookup, MethodLookup Depends on link.xml or addressables to keep members under IL2CPP stripping"},{"location":"features/utilities/reflection-helpers/#current-consumers-snapshot","title":"Current Consumers Snapshot","text":"Runtime/Core/Serialization/Serializer.cs and Runtime/Core/Serialization/JsonConverters/TypeConverter.cs lean on static method invokers and type resolution to integrate ProtoBuf and JSON pipelines.Runtime/Core/Attributes (BaseRelationalComponentAttribute, RelationalComponentInitializer, WNotNullAttribute) depend on field getters/setters and collection factories for relational wiring.Runtime/Tags (AttributeMetadataCache, AttributeUtilities, AttributeMetadataFilters) use attribute scanning plus cached getters/setters to hydrate metadata tables at startup.Runtime/Core/Helper/StringInList.cs and Runtime/Core/Helper/Logging/UnityLogTagFormatter.cs use helper invokers for dynamic lookups during logging and formatting.Editor/AnimationEventEditor.cs, Editor/Tags/AttributeMetadataCacheGenerator.cs, and Editor/Utils/ScriptableObjectSingletonCreator.cs call into the helpers for TypeCache-driven discovery and editor automation.Runtime/Utils/ScriptableObjectSingleton.cs relies on safe attribute retrieval to locate singleton assets without repeating reflection calls.DynamicMethod IL Emit Expression.Compile ReflectionHelpers Behaviour Notes Editor (Windows/macOS/Linux) Mono / JIT \u2705 Enabled (EMIT_DYNAMIC_IL) \u2705 Enabled (SUPPORT_EXPRESSION_COMPILE) Uses IL-generated delegates for getters/setters/invokers; expression compile is a fallback if IL creation fails at runtime Same behaviour for play mode in editor; fastest path used during authoring tools and tests. Standalone Player (Mono scripting backend) Mono / JIT \u2705 Enabled \u2705 Enabled Matches editor experience; cached IL delegates provide best throughput Applies to legacy desktop Mono builds (Windows/Mac/Linux) where JIT is available. Standalone / Mobile / Console (IL2CPP) IL2CPP / AOT \u274c Disabled at compile time (ENABLE_IL2CPP blocks EMIT_DYNAMIC_IL) \u26a0\ufe0f Disabled (SUPPORT_EXPRESSION_COMPILE undefined; CheckExpressionCompilationSupport returns false) Falls back to pre-built delegate wrappers or direct Invoke/GetValue with caching; still avoids repeated reflection lookups Covers Windows/macOS/iOS/Android/Consoles when built with IL2CPP. Requires link.xml (or addressables) to preserve reflected members. WebGL Player IL2CPP / AOT (wasm) \u274c Disabled (UNITY_WEBGL && !UNITY_EDITOR) \u26a0\ufe0f Disabled Uses expression-free reflection paths identical to IL2CPP builds; object boxing unavoidable for struct setters/invokers WebGL disallows runtime codegen; helpers rely on cached reflection only. Burst-compiled jobs Burst \u274c Not permitted \u274c Not permitted ReflectionHelpers should not be called from Burst jobs; wrap calls on main thread or use precomputed data Burst forbids managed reflection; guard usage with Unity.Burst.NoAlias patterns or pre-bake data. Server builds / headless (Mono) Mono / JIT \u2705 Enabled \u2705 Enabled Same as desktop Mono path; suitable for dedicated servers running on JIT Confirm EMIT_DYNAMIC_IL stays enabled unless IL2CPP server build is selected. Continuous Integration Any Depends on selected backend Depends on backend Benchmarks skip doc writes when Helpers.IsRunningInContinuousIntegration is true, but helpers themselves behave per backend Use automated tests to validate both IL2CPP fallback and Mono fast paths. DynamicMethod support is controlled at compile time by #if !((UNITY_WEBGL && !UNITY_EDITOR) || ENABLE_IL2CPP) in ReflectionHelpers.cs.Expression.Compile support is gated by the same define; the runtime guard CheckExpressionCompilationSupport() prevents usage when the platform forbids JIT compilation even if the symbols are present.SINGLE_THREADED builds remove System.Collections.Concurrent usage and swap to simple dictionaries; this is rarely needed but remains AOT-friendly for constrained platforms.Key APIs at a glance
GetFieldGetter(FieldInfo) \u2192 Func<object, object>GetFieldSetter(FieldInfo) \u2192 Action<object, object>GetFieldGetter<TInstance, TValue>(FieldInfo) \u2192 Func<TInstance, TValue>GetFieldSetter<TInstance, TValue>(FieldInfo) \u2192 FieldSetter<TInstance, TValue> (ref setter)GetStaticFieldGetter<T>(FieldInfo) / GetStaticFieldSetter<T>(FieldInfo)GetPropertyGetter(PropertyInfo) / GetPropertySetter(PropertyInfo) (boxed)GetPropertyGetter<TInstance, TValue>(PropertyInfo) (typed)GetStaticPropertyGetter<T>(PropertyInfo)GetMethodInvoker(MethodInfo) / GetStaticMethodInvoker(MethodInfo) (boxed)GetStaticMethodInvoker<TReturn>(MethodInfo), GetStaticMethodInvoker<T1, TReturn>(MethodInfo), GetStaticMethodInvoker<T1, T2, TReturn>(MethodInfo), GetStaticMethodInvoker<T1, T2, T3, TReturn>(MethodInfo), GetStaticMethodInvoker<T1, T2, T3, T4, TReturn>(MethodInfo) (typed)GetStaticActionInvoker(...) arities 0\u20134 (typed, void return)GetInstanceMethodInvoker<TInstance, ...>(MethodInfo) and GetInstanceActionInvoker<TInstance, ...>(MethodInfo) arities 0\u20134GetConstructor(ConstructorInfo) (boxed) and GetParameterlessConstructor<T>()CreateInstance<T>(params object[]) and generic type construction helpersCreateArray(Type, int); GetArrayCreator(Type)GetArrayCreator<T>(), GetListCreator<T>(), GetListWithCapacityCreator<T>(), GetHashSetWithCapacityCreator<T>()CreateList(Type) / CreateList(Type, int); GetListCreator(Type); GetListWithCapacityCreator(Type)CreateHashSet(Type, int); GetHashSetWithCapacityCreator(Type); GetHashSetAdder(Type); typed adder GetHashSetAdder<T>()CreateDictionary(Type, Type, int); GetDictionaryWithCapacityCreator(Type, Type); GetDictionaryCreator<TKey, TValue>()GetAllLoadedAssemblies() / GetAllLoadedTypes()HasAttributeSafe, GetAttributeSafe, GetAllAttributesSafe, etc.GetIndexerGetter(PropertyInfo) and GetIndexerSetter(PropertyInfo)IsComponentEnabled<T>(T) and IsActiveAndEnabled<T>(T)Usage examples
public sealed class Player { public int Score; }\n\nFieldInfo score = typeof(Player).GetField(\"Score\");\nvar getScore = ReflectionHelpers.GetFieldGetter(score); // object -> object\nvar setScore = ReflectionHelpers.GetFieldSetter(score); // (object, object) -> void\n\nvar p = new Player();\nsetScore(p, 42);\nUnityEngine.Debug.Log((int)getScore(p)); // 42\npublic struct Stat { public int Value; }\nFieldInfo valueField = typeof(Stat).GetField(\"Value\");\n\n// Prefer typed ref setter for structs\nvar setValue = ReflectionHelpers.GetFieldSetter<Stat, int>(valueField);\nStat s = default;\nsetValue(ref s, 100);\n// s.Value == 100\nvar prop = typeof(Camera).GetProperty(\"orthographicSize\");\nvar getSize = ReflectionHelpers.GetPropertyGetter<Camera, float>(prop);\nfloat size = getSize(UnityEngine.Camera.main);\nvar prop = typeof(TestPropertyClass).GetProperty(\"InstanceProperty\");\nvar set = ReflectionHelpers.GetPropertySetter<TestPropertyClass, int>(prop);\nvar obj = new TestPropertyClass();\nset(obj, 10);\nMethodInfo concat = typeof(string).GetMethod(\n nameof(string.Concat), new[] { typeof(string), typeof(string) }\n);\nvar concat2 = ReflectionHelpers.GetStaticMethodInvoker<string, string, string>(concat);\nstring joined = concat2(\"Hello \", \"World\");\n// Parameterless constructor\nvar newList = ReflectionHelpers.GetParameterlessConstructor<List<int>>();\nList<int> list = newList();\n\n// Constructor via ConstructorInfo\nConstructorInfo ci = typeof(Dictionary<string, int>)\n .GetConstructor(new[] { typeof(int) });\nvar ctor = ReflectionHelpers.GetConstructor(ci);\nvar dict = (Dictionary<string, int>)ctor(new object[] { 128 });\nvar makeArray = ReflectionHelpers.GetArrayCreator(typeof(Vector3));\nArray positions = makeArray(256); // Vector3[256]\n\nIList names = ReflectionHelpers.CreateList(typeof(string), 64); // List<string>\n\nobject set = ReflectionHelpers.CreateHashSet(typeof(int), 0); // HashSet<int>\nvar add = ReflectionHelpers.GetHashSetAdder(typeof(int));\nadd(set, 1);\nadd(set, 1);\nadd(set, 2);\n// set contains {1, 2}\nvar makeArrayT = ReflectionHelpers.GetArrayCreator<int>();\nint[] ints = makeArrayT(128);\n\nvar makeListT = ReflectionHelpers.GetListCreator<string>();\nIList strings = makeListT();\n\nvar makeSetT = ReflectionHelpers.GetHashSetWithCapacityCreator<int>();\nHashSet<int> intsSet = makeSetT(64);\nvar addT = ReflectionHelpers.GetHashSetAdder<int>();\naddT(intsSet, 5);\nbool hasObsolete = ReflectionHelpers.HasAttributeSafe<ObsoleteAttribute>(typeof(MyComponent));\nvar values = ReflectionHelpers.GetAllAttributeValuesSafe(typeof(MyComponent));\n// e.g., values[\"Obsolete\"] -> ObsoleteAttribute instance\nPerformance tips
GetFieldGetter<TInstance, TValue>, typed static invokers) to avoid boxing and object[] allocations.GetListCreator, GetArrayCreator) in loops to avoid reflection/Activator costs.ReflectionHelperCapabilityMatrixTests resets caches and toggles capabilities around each helper. Run these suites in both expression-enabled and expression-disabled modes when changing caching internals.Tests/Runtime/Performance/ReflectionPerformanceTests to capture before/after numbers for getters, setters, method invokers, and constructors (now including expression vs. dynamic IL comparisons). Record results with each ReflectionDelegateStrategy forced via OverrideReflectionCapabilities so regressions are easy to spot.Clear*Cache helper and call it from tests to keep scenarios isolated.Tests/Runtime/Helper/ReflectionHelperCapabilityMatrixTests twice\u2014once normally and once with REFLECTION_HELPERS_FORCE_REFLECTION=1 (or by wrapping the suite in OverrideReflectionCapabilities(false, false)) to cover accelerated and fallback paths.ReflectionPerformanceTests category inside the Unity Test Runner with LogFullResults enabled; copy the markdown summary into the Reflection Performance benchmarks.When you need to validate the pure-reflection paths (for example, to mimic IL2CPP/WebGL behaviour), override the runtime capability probes inside a using scope:
using (ReflectionHelpers.OverrideReflectionCapabilities(expressions: false, dynamicIl: false))\n{\n // Force expression + IL emit to be unavailable\n Func<TestConstructorClass> ctor = ReflectionHelpers.GetParameterlessConstructor<TestConstructorClass>();\n TestConstructorClass instance = ctor(); // Uses reflection fallback\n\n PropertyInfo indexer = typeof(IndexerClass).GetProperty(\"Item\");\n var getter = ReflectionHelpers.GetIndexerGetter(indexer);\n var setter = ReflectionHelpers.GetIndexerSetter(indexer);\n setter(new IndexerClass(), 42, new object[] { 0 }); // reflection-based path\n}\nThe helper restores the original capability state when disposed, so nested overrides remain safe. Runtime regression tests now cover constructors and indexers in both accelerated and fallback modes.
"},{"location":"features/utilities/reflection-helpers/#il2cppwebgl-notes","title":"IL2CPP/WebGL notes","text":"Important for IL2CPP builds (WebGL, iOS, Android, Consoles):
While ReflectionHelpers itself is IL2CPP-safe, Unity's managed code stripping may remove types or members you're trying to access via reflection. This affects any reflection-based code, not just ReflectionHelpers.
Symptoms of stripping issues:
TypeLoadException or NullReferenceException when calling Type.GetType()FieldInfo or MethodInfo returns null for members that exist in the EditorCreate a link.xml file in your Assets folder:
<linker>\n <!-- Preserve types you access via reflection -->\n <assembly fullname=\"Assembly-CSharp\">\n <!-- Preserve entire type and all members -->\n <type fullname=\"MyNamespace.MyReflectedClass\" preserve=\"all\"/>\n\n <!-- Or preserve specific members -->\n <type fullname=\"MyNamespace.AnotherClass\">\n <method signature=\"System.Void DoSomething()\" />\n <field name=\"importantField\" />\n <property name=\"ImportantProperty\" />\n </type>\n\n <!-- Preserve all types in a namespace -->\n <namespace fullname=\"MyNamespace.ReflectedTypes\" preserve=\"all\"/>\n </assembly>\n</linker>\nBest practices:
Type.GetType(\"MyType\") requires link.xmltypeof() when possible - Direct type references prevent stripping without link.xmlExamples of code that needs link.xml:
C#// \u274c Requires link.xml: Type accessed by name\nType t = Type.GetType(\"MyNamespace.MyClass\");\n\n// \u2705 Safer: Direct type reference\nType t = typeof(MyClass);\n\n// \u274c Requires link.xml: Field accessed by name\nFieldInfo field = typeof(MyClass).GetField(\"myField\", BindingFlags.NonPublic);\n\n// \u2705 Safer: If field is definitely there, link.xml ensures it won't be stripped\nWhen ReflectionHelpers doesn't need link.xml:
GetFieldGetter<MyClass, int>() prevents stripping of MyClass)Thread\u2011safety
SINGLE_THREADED build flag switches to regular dictionaries for very constrained environments.Common pitfalls
FieldInfo/PropertyInfo to static getters/setters will throw clear ArgumentExceptions.GetPropertySetter on those throws.FieldSetter<TInstance, TValue>) to mutate the original struct.ref/out parameters and throw NotSupportedException for such signatures.See also
Visual
This package includes two lightweight, production\u2011ready singleton helpers that make global access patterns safe, consistent, and testable:
RuntimeSingleton<T> \u2014 a component singleton that ensures one instance exists in play mode, optionally persists across scenes, and self\u2011initializes when first accessed.ScriptableObjectSingleton<T> \u2014 a configuration/data singleton backed by a single asset under Resources/, with an editor auto\u2011creator to keep assets present and correctly placed.Odin compatibility: When Odin Inspector is present (ODIN_INSPECTOR defined), these types derive from SerializedMonoBehaviour / SerializedScriptableObject for richer serialization. Without Odin, they fall back to Unity base types. No code changes required.
Resources/ in the Editor.[AutoLoadSingleton] to any RuntimeSingleton<T> or ScriptableObjectSingleton<T> to have it instantiated automatically.TypeCache) and serializes the type name + load phase into AttributeMetadataCache. No manual registration or code-generation is required.SingletonAutoLoader reads the serialized entries and uses reflection to touch each singleton\u2019s Instance during the configured RuntimeInitializeLoadType (default BeforeSplashScreen).Instance manually.[AutoLoadSingleton(RuntimeInitializeLoadType.BeforeSceneLoad)]\npublic sealed class GlobalAudioSettings : ScriptableObjectSingleton<GlobalAudioSettings>\n{\n public float masterVolume = 0.8f;\n}\nQuick decision guide
RuntimeSingleton<T>.ScriptableObjectSingleton<T>.RuntimeSingleton
C#public sealed class GameServices : RuntimeSingleton<GameServices>\n{\n // Optional: keep across scene loads\n protected override bool Preserve => true;\n}\n\n// Use anywhere\nGameServices.Instance.DoThing();\nScriptableObjectSingleton
C#[CreateAssetMenu(menuName = \"Game/Audio Settings\")]\n[ScriptableSingletonPath(\"Settings/Audio\")] // Assets/Resources/Settings/Audio/AudioSettings.asset\npublic sealed class AudioSettings : ScriptableObjectSingleton<AudioSettings>\n{\n public float masterVolume = 0.8f;\n}\n\n// Use anywhere (asset auto\u2011created/moved by the editor tool)\nfloat vol = AudioSettings.Instance.masterVolume;\nContents
ODIN_INSPECTOR), base classes inherit from SerializedMonoBehaviour and SerializedScriptableObject to enable serialization of complex types (dictionaries, polymorphic fields) with Odin drawers.MonoBehaviour/ScriptableObject with no behavior change.RuntimeSingleton<T>T.Instance.Creating the instance on demand when not found in the scene.
ScriptableObjectSingleton<T>
Resources.RuntimeSingleton<T> for ephemeral, per\u2011scene logic or objects that should be duplicated in additive scenes.ScriptableObjectSingleton<T> for save data or level\u2011specific data that should not live in Resources or should have multiple instances.RuntimeSingleton<T> Overview","text":"T.Instance (creates a new GameObject named \"<Type>-Singleton\" and adds T if none exists; otherwise finds an existing active instance).HasInstance lets you check for an existing instance without creating one.Preserve (virtual, default true) controls DontDestroyOnLoad.Example: Simple service
C#using UnityEngine;\nusing WallstopStudios.UnityHelpers.Utils;\n\npublic sealed class GameServices : RuntimeSingleton<GameServices>\n{\n // Disable cross\u2011scene persistence if desired\n protected override bool Preserve => false;\n\n public void Log(string message)\n {\n Debug.Log($\"[GameServices] {message}\");\n }\n}\n\n// Usage from anywhere\nGameServices.Instance.Log(\"Hello world\");\nOdin note: With Odin installed, the class inherits SerializedMonoBehaviour, enabling dictionaries and other complex serialized types.
Common pitfalls:
Instance won\u2019t find it (search excludes inactive objects) and will create a new one.Preserve is true, the instance is detached and marked DontDestroyOnLoad.Lifecycle diagram:
Text OnlyT.Instance \u2500\u252c\u2500 Has _instance? \u2500\u2500\u25b6 return\n \u2502\n \u251c\u2500 Find active T in scene? \u2500\u2500\u25b6 set _instance, return\n \u2502\n \u2514\u2500 Create GameObject(\"T-Singleton\") + Add T\n \u2514\u2500 Awake(): assign _instance, if Preserve: DontDestroyOnLoad\n \u2514\u2500 Start(): if duplicate, log + destroy self\nNotes:
Preserve => false.ScriptableObjectSingleton<T> Overview","text":"T.Instance (lazy\u2011loads from Resources/ using either a custom path or the type name; warns if multiple assets found and chooses the first by name).HasInstance indicates whether the lazy value exists and is not null.[ScriptableSingletonPath(\"Sub/Folder\")] to control the Resources subfolder.Example: Settings asset
C#using WallstopStudios.UnityHelpers.Utils;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\n[ScriptableSingletonPath(\"Settings/Audio\")]\npublic sealed class AudioSettings : ScriptableObjectSingleton<AudioSettings>\n{\n public float musicVolume = 0.8f;\n public bool enableSpatialAudio = true;\n}\n\n// Usage at runtime\nfloat vol = AudioSettings.Instance.musicVolume;\nOdin note: With Odin installed, the class inherits SerializedScriptableObject, so you can safely serialize complex collections without custom drawers.
Asset management tips:
Assets/Resources/ (or under the path from [ScriptableSingletonPath]).Lookup order diagram:
Text OnlyInstance access:\n [1] Resources.LoadAll<T>(custom path from [ScriptableSingletonPath])\n [2] if none: Resources.Load<T>(type name)\n [3] if none: Resources.LoadAll<T>(root)\n [4] if multiple: warn + pick first by name (sorted)\nAuto\u2011creator flow (Editor):
Text OnlyOn editor load:\n - Scan all ScriptableObjectSingleton<T> types\n - For each non-abstract type:\n - Determine Resources path (attribute or type name)\n - Ensure folder under Assets/Resources\n - If asset exists elsewhere: move to target path\n - Else: create new asset at target path\n - Save & Refresh if changes\nAsset structure diagram:
Text OnlyDefault (no attribute):\nAssets/\n Resources/\n AudioSettings.asset // type name\n\nWith [ScriptableSingletonPath(\"Settings/Audio\")]:\nAssets/\n Resources/\n Settings/\n Audio/\n AudioSettings.asset\nUnityMainThreadDispatcher which derives from RuntimeSingleton<UnityMainThreadDispatcher>.ScriptableObjectSingleton<T> so data lives in a single editable asset and loads fast.Preserve = true to avoid duplicates across scene loads.ScriptableObject singletons excel as in\u2011project \u201cdatabases\u201d for content/config:
Example: Items DB with indices
C#using System.Collections.Generic;\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Utils;\n\n[CreateAssetMenu(menuName = \"Game/Items DB\")]\n[ScriptableSingletonPath(\"DB\")] // Assets/Resources/DB/ItemsDb.asset\npublic sealed class ItemsDb : ScriptableObjectSingleton<ItemsDb>\n{\n [System.Serializable]\n public sealed class ItemDef { public int id; public string name; public Sprite icon; }\n\n public List<ItemDef> items = new();\n\n // Non-serialized runtime indices\n private readonly Dictionary<int, ItemDef> _byId = new();\n private readonly Dictionary<string, List<ItemDef>> _byName = new();\n\n private void OnEnable() => RebuildIndices();\n private void OnValidate() => RebuildIndices();\n\n private void RebuildIndices()\n {\n _byId.Clear();\n _byName.Clear();\n foreach (var it in items)\n {\n if (it == null) continue;\n _byId[it.id] = it;\n (_byName.TryGetValue(it.name, out var list) ? list : (_byName[it.name] = new())).Add(it);\n }\n }\n\n public static bool TryGetById(int id, out ItemDef def) => Instance._byId.TryGetValue(id, out def);\n}\n\n// Usage\nif (ItemsDb.TryGetById(42, out var sword)) { /* equip sword */ }\nTips
Assets/Resources/Wallstop Studios/Unity Helpers/ScriptableObjectSingletonMetadata.asset, which records the exact Resources load path + GUID for every singleton asset. At runtime, ScriptableObjectSingleton<T> consults this metadata so it can call Resources.Load(\"Folder/MySingleton\") directly (or Resources.LoadAll scoped to Folder/ when it needs to detect duplicates) and never falls back to Resources.LoadAll(string.Empty).Resources.Load<T>(typeName) + editor-only AssetDatabase lookups) instead of scanning the entire Resources tree.[ScriptableSingletonPath] to place the asset predictably under Resources/.OnValidate.using System.Collections.Generic;\nusing UnityEngine;\nusing WallstopStudios.UnityHelpers.Utils;\n#if UNITY_EDITOR\nusing UnityEditor;\nusing UnityEditor.AddressableAssets;\nusing UnityEditor.AddressableAssets.Settings;\n#endif\nusing UnityEngine.AddressableAssets;\n\npublic enum ContentCategory { Weapon, Armor, Consumable, Quest }\n\n[CreateAssetMenu(menuName = \"Game/Content DB\")]\n[ScriptableSingletonPath(\"DB\")] // Assets/Resources/DB/ContentDb.asset\npublic sealed class ContentDb : ScriptableObjectSingleton<ContentDb>\n{\n [System.Serializable]\n public sealed class ContentDef\n {\n public string guid; // stable ID for saves/mods\n public string displayName;\n public ContentCategory category;\n public string[] tags; // e.g., \"fire\", \"ranged\"\n public AssetReferenceGameObject prefab; // addressable ref (optional)\n }\n\n public List<ContentDef> entries = new();\n\n // Indices (runtime only)\n private readonly Dictionary<string, ContentDef> _byGuid = new();\n private readonly Dictionary<ContentCategory, List<ContentDef>> _byCategory = new();\n private readonly Dictionary<string, List<ContentDef>> _byTag = new();\n\n private void OnEnable() => RebuildIndices();\n private void OnValidate() { RebuildIndices(); ValidateEditor(); }\n\n private void RebuildIndices()\n {\n _byGuid.Clear(); _byCategory.Clear(); _byTag.Clear();\n foreach (var e in entries)\n {\n if (e == null || string.IsNullOrEmpty(e.guid)) continue;\n _byGuid[e.guid] = e;\n (_byCategory.TryGetValue(e.category, out var listCat) ? listCat : (_byCategory[e.category] = new())).Add(e);\n if (e.tags != null)\n foreach (var t in e.tags)\n if (!string.IsNullOrEmpty(t))\n (_byTag.TryGetValue(t, out var listTag) ? listTag : (_byTag[t] = new())).Add(e);\n }\n }\n\n public static bool TryGetByGuid(string guid, out ContentDef def) => Instance._byGuid.TryGetValue(guid, out def);\n public static IReadOnlyList<ContentDef> GetByCategory(ContentCategory cat) =>\n Instance._byCategory.TryGetValue(cat, out var list) ? list : (IReadOnlyList<ContentDef>)System.Array.Empty<ContentDef>();\n public static IReadOnlyList<ContentDef> GetByTag(string tag) =>\n Instance._byTag.TryGetValue(tag, out var list) ? list : (IReadOnlyList<ContentDef>)System.Array.Empty<ContentDef>();\n\n#if UNITY_EDITOR\n private void ValidateEditor()\n {\n // Validate GUID uniqueness\n var seen = new HashSet<string>();\n foreach (var e in entries)\n {\n if (e == null) continue;\n if (string.IsNullOrEmpty(e.guid))\n Debug.LogWarning($\"[ContentDb] Entry '{e?.displayName}' has empty GUID\", this);\n else if (!seen.Add(e.guid))\n Debug.LogError($\"[ContentDb] Duplicate GUID '{e.guid}' detected\", this);\n }\n\n // Validate Addressables (if package installed and editor context)\n var settings = AddressableAssetSettingsDefaultObject.Settings;\n if (settings != null)\n {\n foreach (var e in entries)\n {\n if (e?.prefab == null) continue;\n var guid = e.prefab.AssetGUID;\n if (string.IsNullOrEmpty(guid) || settings.FindAssetEntry(guid) == null)\n Debug.LogWarning($\"[ContentDb] Prefab for '{e.displayName}' is not marked Addressable\", this);\n }\n }\n }\n#endif\n}\nWhy this works well
Use alternatives when one or more of these apply:
Use this chart to pick an approach based on constraints:
"},{"location":"features/utilities/singletons/#testing-patterns","title":"Testing Patterns","text":""},{"location":"features/utilities/singletons/#testing-with-runtimesingletont","title":"Testing withRuntimeSingleton<T>","text":"Runtime singletons require special handling in tests to avoid leaked GameObjects and unpredictable state across test runs. The recommended pattern uses CommonTestBase which handles cleanup automatically.
using WallstopStudios.UnityHelpers.Tests.Core;\n\npublic sealed class MyServiceTests : CommonTestBase\n{\n [Test]\n public void MyServiceInitializesCorrectly()\n {\n // CommonTestBase automatically manages dispatcher lifecycle\n // and cleans up any spawned GameObjects after each test\n var service = MyService.Instance;\n Assert.That(service != null);\n }\n}\nFor tests that need finer control over singleton lifecycle:
C#using UnityMainThreadDispatcher = WallstopStudios.UnityHelpers.Core.Helper.UnityMainThreadDispatcher;\n\npublic sealed class CustomSingletonTests\n{\n private UnityMainThreadDispatcher.AutoCreationScope _scope;\n\n [SetUp]\n public void SetUp()\n {\n // Disable auto-creation, destroy any existing instance, then re-enable\n _scope = UnityMainThreadDispatcher.CreateTestScope(destroyImmediate: true);\n }\n\n [TearDown]\n public void TearDown()\n {\n // Restores previous auto-creation state and destroys test-created instances\n _scope?.Dispose();\n _scope = null;\n }\n\n [Test]\n public void DispatcherIsAvailableInTest()\n {\n var dispatcher = UnityMainThreadDispatcher.Instance;\n Assert.That(dispatcher != null);\n }\n}\nFor specific tests that need to verify behavior when the singleton doesn't exist:
C#[Test]\npublic void CodeHandlesMissingDispatcherGracefully()\n{\n using (UnityMainThreadDispatcher.AutoCreationScope.Disabled(\n destroyExistingInstanceOnEnter: true,\n destroyInstancesOnDispose: true,\n destroyImmediate: true))\n {\n // Inside this scope, accessing Instance won't auto-create\n bool hasInstance = UnityMainThreadDispatcher.HasInstance;\n Assert.That(hasInstance, Is.False);\n }\n // Auto-creation restored after scope exits\n}\nScriptableObjectSingleton<T>","text":"ScriptableObject singletons load from Resources/ and are typically tested in Editor tests where asset manipulation is possible.
using WallstopStudios.UnityHelpers.Tests.Core;\n#if UNITY_EDITOR\nusing UnityEditor;\n#endif\n\npublic sealed class AudioSettingsTests : CommonTestBase\n{\n [Test]\n public void AudioSettingsLoadsFromResources()\n {\n // ScriptableObjectSingleton loads lazily from Resources\n var settings = AudioSettings.Instance;\n Assert.That(settings != null);\n Assert.That(settings.masterVolume, Is.InRange(0f, 1f));\n }\n}\nFor tests that need controlled data:
C##if UNITY_EDITOR\n[Test]\npublic void SettingsWithCustomValuesWork()\n{\n // Create a test instance (tracked by CommonTestBase for cleanup)\n var testSettings = CreateScriptableObject<AudioSettings>();\n testSettings.masterVolume = 0.5f;\n\n // Test logic using the instance directly (not via Instance property)\n Assert.That(testSettings.masterVolume, Is.EqualTo(0.5f));\n}\n#endif\nInherit from CommonTestBase: This handles most singleton cleanup automatically, including dispatcher scope management.
Use CreateTestScope for dispatcher: The UnityMainThreadDispatcher.CreateTestScope() method packages the common test setup pattern: disable auto-creation \u2192 destroy existing \u2192 re-enable auto-creation.
Prefer destroyImmediate: true in EditMode: EditMode tests should use DestroyImmediate to ensure synchronous cleanup without Unity's delayed destruction.
Track created objects: Use Track<T>() or TrackDisposable<T>() to ensure objects are cleaned up after tests.
Clear singleton state between tests: Domain reloads clear singleton instances, but within a test run you may need explicit cleanup.
Preserve => false to prevent cross-scene persistence.Resources/ for each ScriptableObjectSingleton<T>; let the auto-creator relocate any strays.[ScriptableSingletonPath] to group related settings; avoid deep nesting that hurts discoverability.With Odin installed, take advantage of Serialized* bases for complex serialized fields; without Odin, keep fields Unity-serializable.
Multiple ScriptableObject assets found: a warning is logged and the first by name is used. Resolve by keeping only one asset in Resources or by letting the auto\u2011creator relocate the correct one.
Instance returns null for ScriptableObject: Ensure the asset exists under Resources/ and the type name or custom path matches.CommonTestBase or wrap test code with AutoCreationScope.Disabled() to ensure cleanup.Tests/Runtime/Utils/RuntimeSingletonTests.cs and Tests/Editor/Utils/ScriptableObjectSingletonTests.cs.A practical guide for migrating from Odin Inspector to Unity Helpers. Examples are verified against the actual source code.
"},{"location":"guides/odin-migration-guide/#quick-reference-table","title":"Quick Reference Table","text":"Odin Feature Unity Helpers Equivalent[Button] [WButton] [ReadOnly] [WReadOnly] [ShowIf] / [HideIf] [WShowIf] [EnumToggleButtons] [WEnumToggleButtons] [ValueDropdown] [WValueDropDown], [IntDropDown], [StringInList] [BoxGroup] [WGroup] [FoldoutGroup] [WGroup(collapsible: true)] [InlineEditor] [WInLineEditor] [Required] [WNotNull], [ValidateAssignment] SerializedMonoBehaviour Standard MonoBehaviour SerializedDictionary SerializableDictionary<K,V> N/A (paid feature) SerializableHashSet<T>"},{"location":"guides/odin-migration-guide/#1-serializable-collections","title":"1. Serializable Collections","text":""},{"location":"guides/odin-migration-guide/#dictionary","title":"Dictionary","text":"Odin:
C#using Sirenix.OdinInspector;\nusing Sirenix.Serialization;\n\npublic class Example : SerializedMonoBehaviour\n{\n public Dictionary<string, int> scores;\n}\nUnity Helpers:
C#using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.DataStructure.Adapters;\n\npublic class Example : MonoBehaviour\n{\n [SerializeField]\n private SerializableDictionary<string, int> scores = new SerializableDictionary<string, int>();\n}\nKey differences:
MonoBehaviour)[SerializeField] or publicnew to avoid null references (good practice, Unity will initialize this like it does List and arrays)"},{"location":"guides/odin-migration-guide/#hashset","title":"HashSet","text":"Odin:
C#using Sirenix.OdinInspector;\nusing Sirenix.Serialization;\n\npublic class Example : SerializedMonoBehaviour\n{\n public HashSet<string> unlockedItems;\n}\nUnity Helpers:
C#using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.DataStructure.Adapters;\n\npublic class Example : MonoBehaviour\n{\n [SerializeField]\n private SerializableHashSet<string> unlockedItems = new SerializableHashSet<string>();\n}\nOdin:
C#[Button(\"Regenerate\")]\nprivate void RegenerateLevel() { }\n\n[Button, ButtonGroup(\"Actions\")]\nprivate void Save() { }\nUnity Helpers:
C#[WButton(\"Regenerate\")]\nprivate void RegenerateLevel() { }\n\n[WButton(groupName: \"Actions\")]\nprivate void Save() { }\nAdditional options:
C#// Control button order within a group\n[WButton(drawOrder: 1, groupName: \"Debug\")]\nprivate void PrintDebugInfo() { }\n\n// Control group placement (top or bottom of inspector)\n[WButton(groupName: \"Authoring\", groupPlacement: WButtonGroupPlacement.Top)]\nprivate void GenerateIds() { }\nOdin Inspector Support:
WButton works with Odin's SerializedMonoBehaviour and SerializedScriptableObject without additional setup. Use [WButton] on your methods.
Manual integration may be needed if:
OdinEditor for a specific typeOdin:
C#public bool showAdvanced;\n\n[ShowIf(\"showAdvanced\")]\npublic float advancedSetting;\nUnity Helpers:
C#public bool showAdvanced;\n\n[WShowIf(nameof(showAdvanced))]\npublic float advancedSetting;\nOdin:
C#[HideIf(\"isDisabled\")]\npublic float value;\nUnity Helpers:
C#[WShowIf(nameof(isDisabled), inverse: true)]\npublic float value;\nOdin:
C#public AttackType attackType;\n\n[ShowIf(\"attackType\", AttackType.Ranged)]\npublic float range;\nUnity Helpers:
C#public AttackType attackType;\n\n[WShowIf(nameof(attackType), AttackType.Ranged)]\npublic float range;\nOdin:
C#[ShowIf(\"@level >= 5\")]\npublic Ability ultimateAbility;\nUnity Helpers:
C#[WShowIf(nameof(level), WShowIfComparison.GreaterThanOrEqual, 5)]\npublic Ability ultimateAbility;\nAvailable comparisons: Equal, NotEqual, GreaterThan, GreaterThanOrEqual, LessThan, LessThanOrEqual, IsNull, IsNotNull, IsNullOrEmpty, IsNotNullOrEmpty
Odin:
C#[EnumToggleButtons]\npublic Direction direction;\n\n[EnumToggleButtons]\npublic MovementFlags flags; // [Flags] enum\nUnity Helpers:
C#[WEnumToggleButtons]\npublic Direction direction;\n\n[WEnumToggleButtons(showSelectAll: true, showSelectNone: true)]\npublic MovementFlags flags; // [Flags] enum\nControl buttons per row:
C#[WEnumToggleButtons(buttonsPerRow: 4)]\npublic DamageType damageTypes;\nOdin:
C#[ValueDropdown(\"GetFrameRates\")]\npublic int targetFrameRate;\n\nprivate int[] GetFrameRates() => new[] { 30, 60, 120 };\nUnity Helpers:
C#// Inline values (simplest)\n[IntDropDown(30, 60, 120)]\npublic int targetFrameRate;\n\n// Or with provider method\n[IntDropDown(nameof(GetFrameRates))]\npublic int targetFrameRate;\n\nprivate IEnumerable<int> GetFrameRates() => new[] { 30, 60, 120 };\nOdin:
C#[ValueDropdown(\"GetDifficulties\")]\npublic string difficulty;\nUnity Helpers:
C#// Inline values\n[StringInList(\"Easy\", \"Normal\", \"Hard\")]\npublic string difficulty;\n\n// Or with provider\n[StringInList(nameof(GetDifficulties))]\npublic string difficulty;\nUnity Helpers:
C#// Static provider from another class\n[WValueDropDown(typeof(AudioManager), nameof(AudioManager.GetSoundNames))]\npublic string soundEffect;\n\n// Instance provider (method on same class)\n[WValueDropDown(nameof(GetAvailableWeapons), typeof(WeaponData))]\npublic WeaponData selectedWeapon;\nOdin:
C#[BoxGroup(\"Movement\")]\npublic float speed;\n\n[BoxGroup(\"Movement\")]\npublic float jumpHeight;\n\n[FoldoutGroup(\"Advanced\")]\npublic float acceleration;\nUnity Helpers:
C#// Auto-include next N fields\n[WGroup(\"Movement\", autoIncludeCount: 2)]\npublic float speed; // Field 1: in group\npublic float jumpHeight; // Field 2: in group (auto-included, last by count)\n\n// Or explicit end marker\n[WGroup(\"Movement\")]\npublic float speed; // In group\npublic float jumpHeight; // In group (auto-included)\n[WGroupEnd] // friction IS included, then group closes\npublic float friction; // In group (last field)\n\n// Collapsible (foldout)\n[WGroup(\"Advanced\", collapsible: true, startCollapsed: true)]\npublic float acceleration;\nUnity Helpers:
C#[WGroup(\"Character\", displayName: \"Character Settings\")]\npublic string characterName;\n\n[WGroup(\"Stats\", parentGroup: \"Character\")]\npublic int health;\npublic int mana;\nOdin:
C#[InlineEditor]\npublic EnemyConfig config;\n\n[InlineEditor(InlineEditorModes.GUIOnly)]\npublic ItemData item;\nUnity Helpers:
C#[WInLineEditor]\npublic EnemyConfig config;\n\n[WInLineEditor(WInLineEditorMode.FoldoutExpanded, inspectorHeight: 200f)]\npublic ItemData item;\nAvailable modes: AlwaysExpanded, FoldoutExpanded, FoldoutCollapsed
Odin:
C#[Required]\npublic GameObject prefab;\n\n[Required(\"Player reference is required!\")]\npublic Transform player;\nUnity Helpers:
C#[WNotNull]\npublic GameObject prefab;\n\n[WNotNull(WNotNullMessageType.Error, \"Player reference is required!\")]\npublic Transform player;\n\n// Runtime validation in Awake/Start\nprivate void Awake()\n{\n this.CheckForNulls(); // Extension method\n}\nFor validating that collections aren't empty:
C#[ValidateAssignment]\npublic List<Transform> spawnPoints; // Warns if null or empty\n\n[ValidateAssignment(ValidateAssignmentMessageType.Error, \"Need at least one enemy type\")]\npublic List<EnemyData> enemyTypes;\n\n// Runtime check\nprivate void Start()\n{\n this.ValidateAssignments();\n}\nOdin:
C#[ReadOnly]\npublic string generatedId;\nUnity Helpers:
C#[WReadOnly]\npublic string generatedId;\nBefore (Odin):
C#using Sirenix.OdinInspector;\nusing Sirenix.Serialization;\nusing UnityEngine;\nusing System.Collections.Generic;\n\npublic class EnemySpawner : SerializedMonoBehaviour\n{\n [BoxGroup(\"Settings\")]\n [Required]\n public GameObject enemyPrefab;\n\n [BoxGroup(\"Settings\")]\n [ShowIf(\"useWaves\")]\n public int wavesCount = 3;\n\n public bool useWaves;\n\n [EnumToggleButtons]\n public SpawnPattern pattern;\n\n [ValueDropdown(\"GetSpawnRates\")]\n public float spawnRate;\n\n public Dictionary<string, int> enemyWeights;\n\n [Button(\"Spawn Wave\")]\n private void SpawnWave() { }\n\n private float[] GetSpawnRates() => new[] { 0.5f, 1f, 2f };\n}\nAfter (Unity Helpers):
C#using UnityEngine;\nusing System.Collections.Generic;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\nusing WallstopStudios.UnityHelpers.Core.DataStructure.Adapters;\n\npublic class EnemySpawner : MonoBehaviour\n{\n [WGroup(\"Settings\", autoIncludeCount: 2)]\n [WNotNull]\n [SerializeField]\n private GameObject enemyPrefab;\n\n [WShowIf(nameof(useWaves))]\n [SerializeField]\n private int wavesCount = 3;\n\n [SerializeField]\n private bool useWaves;\n\n [WEnumToggleButtons]\n [SerializeField]\n private SpawnPattern pattern;\n\n [WValueDropDown(0.5f, 1f, 2f)]\n [SerializeField]\n private float spawnRate;\n\n [SerializeField]\n private SerializableDictionary<string, int> enemyWeights =\n new SerializableDictionary<string, int>();\n\n [WButton(\"Spawn Wave\")]\n private void SpawnWave() { }\n}\n// Attributes\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\n// Serializable collections\nusing WallstopStudios.UnityHelpers.Core.DataStructure.Adapters;\nMonoBehaviour / ScriptableObjectnameof() - Unity Helpers uses nameof() for condition fields (type-safe)new SerializableDictionary<K,V>() etc. to avoid null references[WShowIf(..., inverse: true)] instead of [HideIf]WShowIfComparison enum instead of expression strings[WGroup] can auto-include subsequent fields with autoIncludeCountAlphabetical index of all Unity Helpers features with quick links to documentation.
Quick Navigation: A | B | C | D | E | F | G | H | I | K | L | M | N | O | P | Q | R | S | T | U | V | W | X
"},{"location":"overview/#a","title":"A","text":"Animation Copier - Sync AnimationClips between folders \u2192 Editor Tools Guide
Animation Creator - Bulk-create clips from sprite naming patterns \u2192 Editor Tools Guide
Animation Event Editor - Visual event editing with sprite preview \u2192 Editor Tools Guide
AnimatedSpriteLayer - Data structure for sprite animation layers \u2192 Visual Components
AnimatorEnumStateMachine - Type-safe enum-based animator control \u2192 Utility Components
Async Extensions - Await AsyncOperation with Task/ValueTask \u2192 Math & Extensions
Attribute - Dynamic numeric value with modifications \u2192 Effects System | Glossary
Attribute Metadata Cache - Pre-computed attribute reflection data \u2192 Editor Tools Guide
AttributeEffect - ScriptableObject for data-driven gameplay effects \u2192 Effects System
AttributesComponent - Base class for modifiable attributes \u2192 Effects System | README
"},{"location":"overview/#b","title":"B","text":"Binary Heap - Priority queue with O(log n) operations \u2192 Data Structures
BitSet - Compact boolean storage with bitwise operations \u2192 Data Structures | README
Buffering Pattern - Reusable collections for zero-allocation queries \u2192 README - Buffering Pattern | Glossary
Buffers - Pooled collections (List/Stack/Queue/HashSet) \u2192 README - Buffering Pattern"},{"location":"overview/#c","title":"C","text":"
Camera Extensions - OrthographicBounds and helpers \u2192 Math & Extensions
CenterPointOffset - Define logical center points separate from transform pivot \u2192 Utility Components
ChildComponent - Auto-wire components from children \u2192 Relational Components | README
ChildSpawner - Conditional prefab instantiation with environment filtering \u2192 Utility Components
CircleLineRenderer - Dynamic circle visualization synced to CircleCollider2D \u2192 Utility Components
CollisionProxy - Event-based 2D collision detection without inheritance \u2192 Utility Components
Color Utilities - Averaging (LAB/HSV/Weighted/Dominant), hex conversion \u2192 Math & Extensions
CoroutineHandler - Singleton MonoBehaviour for coroutine hosting \u2192 Utility Components
CosmeticEffectData - Presenters for effect cosmetics \u2192 Effects System
Cyclic Buffer - Fixed-capacity ring buffer \u2192 Data Structures | README
"},{"location":"overview/#d","title":"D","text":"Data Structures - Heaps, tries, sparse sets, and more \u2192 Data Structures Guide | README
Deque - Double-ended queue \u2192 Data Structures | README
Dictionary Extensions - GetOrAdd, GetOrElse, Merge, ContentEquals \u2192 Math & Extensions
Disjoint Set - Union-find for connectivity \u2192 Data Structures | README
Douglas-Peucker - Polyline simplification algorithm \u2192 Math & Extensions | Glossary
WReadOnly - Read-only inspector display attribute \u2192 Editor Tools Guide | README
"},{"location":"overview/#e","title":"E","text":"Editor Tools - 20+ tools for sprites, animations, validation \u2192 Editor Tools Guide | README
EffectHandle - Identifier for effect application instances \u2192 Effects System | Glossary
EffectHandler - Component managing effect lifecycle \u2192 Effects System
Effects System - Data-driven buffs/debuffs/status effects \u2192 Effects System Guide | README
EnhancedImage - Unity Image with HDR color and shape masks \u2192 Visual Components | Editor Tools Guide
Enum Extensions - Zero-allocation flag checks, cached names, display names \u2192 Math & Extensions
"},{"location":"overview/#f","title":"F","text":"Failed Tests Exporter - Capture and export failed test results to timestamped files \u2192 Failed Tests Exporter
Fit Texture Size - Auto-adjust texture max size to source dimensions \u2192 Editor Tools Guide
FlurryBurstRandom - Six-word ARX generator (FlurryBurst32 port) \u2192 README - Random Generators | Random Performance
"},{"location":"overview/#g","title":"G","text":"Gaussian Distribution - Normal distribution random values \u2192 README - Random Generators
Geometry Helpers - Lines, ranges, parabolas, convex hulls \u2192 Math & Extensions
Glossary - Term definitions \u2192 Glossary
"},{"location":"overview/#h","title":"H","text":"Heap - Binary heap for priority queues \u2192 Data Structures | README
Helpers Class - General utilities (layers, sprites, components) \u2192 Helper Utilities | README
Hulls - Convex vs concave hull algorithms \u2192 Hulls Guide
"},{"location":"overview/#i","title":"I","text":"IllusionFlow - Default recommended PRNG \u2192 README - Random Generators | Random Performance
Image Blur Tool - Gaussian blur for textures \u2192 Editor Tools Guide
Immutable Trees - Spatial trees requiring rebuild on changes \u2192 Spatial Trees 2D | Glossary
Inspector Settings - Project-wide configuration for inspector features (pagination, colors, animations) \u2192 Inspector Settings
Inspector Tooling Overview - Complete guide to inspector attributes and serialization types \u2192 Inspector Overview
IntDropdown - Integer dropdown property drawer \u2192 Editor Tools Guide | Inspector Selection Attributes
IRandom Interface - Common interface for all RNGs \u2192 README - Random Generators
"},{"location":"overview/#k","title":"K","text":"KdTree2D - 2D k-dimensional tree for nearest neighbors \u2192 2D Spatial Trees | 2D Performance
KdTree3D - 3D k-dimensional tree for nearest neighbors \u2192 3D Spatial Trees | 3D Performance
"},{"location":"overview/#l","title":"L","text":"LayeredImage - UI Toolkit element for composited sprite animations \u2192 Visual Components
Line2D / Line3D - Line segment operations \u2192 Math & Extensions
LineHelper - Douglas-Peucker simplification \u2192 Math & Extensions | README
llms.txt - LLM-friendly documentation for AI assistants \u2192 llms.txt
LoggingExtensions - Color-coded, thread-safe logging utilities \u2192 Logging Extensions
LZMA Compression - Compression utilities \u2192 README - Serialization
"},{"location":"overview/#m","title":"M","text":"Math Helpers - Positive modulo, wrapped arithmetic, geometry \u2192 Math & Extensions Guide | README
MatchColliderToSprite - Sync collider shape to sprite \u2192 Utility Components | Editor Tools Guide
MatchTransform - Follow another transform with offset and timing control \u2192 Utility Components
"},{"location":"overview/#n","title":"N","text":"Noise Maps - Perlin noise generation \u2192 README - Random Generators
WNotNull Attribute - Inspector validation attribute \u2192 README
Numeric Helpers - PositiveMod, Clamp, Approximately \u2192 Math & Extensions
"},{"location":"overview/#o","title":"O","text":"Oscillator - Automatic circular/elliptical motion component \u2192 Utility Components
OctTree3D - 3D spatial tree (octree) \u2192 3D Spatial Trees | 3D Performance
Odin Inspector Migration - Step-by-step guide for migrating from Odin Inspector \u2192 Migration Guide
Odin Compatibility - Automatic Odin Inspector integration \u2192 Singletons - Odin | Glossary
"},{"location":"overview/#p","title":"P","text":"Parabola - Parabolic trajectory helper \u2192 Math & Extensions
ParentComponent - Auto-wire components from parents \u2192 Relational Components | README
PcgRandom - High-quality PCG random generator \u2192 README - Random Generators | Random Performance
PhotonSpinRandom - SHISHUA-inspired bulk generator \u2192 README - Random Generators | Random Performance
Point-in-Polygon - 2D/3D containment tests \u2192 Math & Extensions
PolygonCollider2DOptimizer - Simplify collider points \u2192 Utility Components | Editor Tools Guide
Predictive Aiming - Calculate where to aim at moving targets \u2192 Helper Utilities
Pooled Buffers - Reusable memory allocations \u2192 README - Buffering Pattern | Glossary
Positive Modulo - Non-negative modulo operation \u2192 Math & Extensions | Glossary
Prefab Checker - Comprehensive prefab validation \u2192 Editor Tools Guide
PriorityQueue - Min/max heap-based priority queue \u2192 Data Structures | README
PRNG.Instance - Thread-local default random generator \u2192 README - Random Generators
Property Drawers - Custom inspector rendering \u2192 Editor Tools Guide
Protobuf Serialization - Compact binary serialization \u2192 Serialization Guide | Glossary
"},{"location":"overview/#q","title":"Q","text":"QuadTree2D - 2D spatial tree (quadtree) \u2192 2D Spatial Trees | 2D Performance
"},{"location":"overview/#r","title":"R","text":"Random Extensions - Random vectors, colors, weighted selection, subset sampling \u2192 Random Generators Guide
Random Generators - 15 high-performance PRNG implementations \u2192 Random Generators Guide | Random Performance
Range - Inclusive/exclusive range helper \u2192 Math & Extensions
Rect/Bounds Extensions - Conversions and aggregation \u2192 Math & Extensions
RectTransform Extensions - GetWorldRect and helpers \u2192 Math & Extensions
Reflection Helpers - High-performance cached reflection \u2192 Reflection Helpers
Relational Components - Auto-wire hierarchy components \u2192 Relational Components Guide | Relational Component Performance Benchmarks
RTree2D - 2D R-tree for bounding boxes \u2192 2D Spatial Trees | 2D Performance
RTree3D - 3D R-tree for bounding volumes \u2192 3D Spatial Trees | 3D Performance
RuntimeSingleton - Component singleton pattern \u2192 Singletons Guide | Testing Patterns | README"},{"location":"overview/#s","title":"S","text":"
ScriptableObject Singleton - Settings/data singleton pattern \u2192 Singletons Guide | Testing Patterns | README
ScriptableObject Singleton Creator - Auto-create singleton assets \u2192 Editor Tools Guide
Serialization - JSON, Protobuf, BinaryFormatter support \u2192 Serialization Guide | README
SiblingComponent - Auto-wire components on same GameObject \u2192 Relational Components | README
SerializableDictionary - Unity-friendly dictionary with key/value serialization \u2192 Serialization Types
SerializableHashSet / SerializableSortedSet - Unity-friendly set collections \u2192 Serialization Types
SerializableNullable - Unity-friendly nullable value wrapper \u2192 Serialization Types
SerializableType - Type reference that survives refactoring \u2192 Serialization Types
Singletons - Runtime and ScriptableObject singleton patterns \u2192 Singletons Guide | README
StormDropRandom - Large-buffer ARX generator \u2192 README - Random Generators | Random Performance
Sparse Set - O(1) membership with dense iteration \u2192 Data Structures | README
Spatial Hash 2D/3D - Grid-based spatial structure \u2192 2D Spatial Trees | 3D Spatial Trees
Spatial Trees - Fast spatial queries (QuadTree, KdTree, RTree, OctTree) \u2192 2D Guide | 3D Guide
Spatial Tree Semantics - Boundary behavior and edge cases \u2192 Spatial Tree Semantics
Sprite Animation Editor - Visual animation editing with preview \u2192 Editor Tools Guide
Sprite Atlas Generator - Regex/label-based atlas creation \u2192 Editor Tools Guide
Sprite Cropper - Remove transparent padding \u2192 Editor Tools Guide
Sprite Label Processor - Auto-cache sprite labels \u2192 Editor Tools Guide
Sprite Pivot Adjuster - Alpha-weighted pivot adjustment \u2192 Editor Tools Guide
Sprite Settings Applier - Batch sprite import settings \u2192 Editor Tools Guide
Sprite Sheet Animation Creator - Convert sprite sheets to clips \u2192 Editor Tools Guide
SpriteRendererMetadata - Stack-based color and material management \u2192 Utility Components
SpriteRendererSync - Mirror SpriteRenderer properties to another renderer \u2192 Utility Components
StartTracker - Track MonoBehaviour Start() lifecycle event \u2192 Utility Components
String Extensions - Casing, encoding, Levenshtein distance, Base64, analysis \u2192 Math & Extensions
StringInList - String dropdown property drawer with search and pagination \u2192 Inspector Selection Attributes | Editor Tools Guide
"},{"location":"overview/#t","title":"T","text":"Tag Handler - Reference-counted string tags \u2192 Effects System | Glossary
Texture Resizer - Batch resize with bilinear/point filtering \u2192 Editor Tools Guide
Texture Settings Applier - Batch texture import settings \u2192 Editor Tools Guide
Trie - Prefix tree for autocomplete \u2192 Data Structures | README
"},{"location":"overview/#u","title":"U","text":"Unity Extensions - Rect/Bounds, Camera, Rigidbody2D, Grid helpers \u2192 Math & Extensions
UnityMainThreadDispatcher - Execute work on main thread from background threads \u2192 Threading Guide | Helper Utilities
"},{"location":"overview/#v","title":"V","text":"ValidateAssignment - Inspector validation attribute \u2192 Relational Components
Vector Extensions - Random vectors, noise detection \u2192 Math & Extensions
"},{"location":"overview/#w","title":"W","text":"WallMath - Positive modulo, wrapped arithmetic \u2192 Math & Extensions
WallstopArrayPool - Pooled array rental \u2192 README - Buffering Pattern
WallstopFastArrayPool - Fast array pool for short-lived arrays (T : unmanaged) \u2192 README - Buffering Pattern
WButton - Inspector method buttons with history, async support, cancellation \u2192 Inspector Buttons | Inspector Overview
WEnumToggleButtons - Enum and flag enum toggle button toolbars \u2192 Inspector Selection Attributes
WGuid - Immutable version-4 GUID using two longs for fast Unity serialization \u2192 Serialization Types
WGroup / WGroupEnd - Boxed inspector sections with auto-inclusion, palette-driven styling, and optional collapsible headers \u2192 Inspector Grouping Attributes
Weighted Random - Weighted random selection \u2192 README - Random Generators
WInLineEditor - Inline inspector for object references \u2192 Editor Tools Guide | README - Relational Components
WShowIf - Conditional field display attribute with comparison operators \u2192 Inspector Conditional Display | Editor Tools Guide
WValueDropDown - Generic dropdown for any type with fixed values or providers \u2192 Inspector Selection Attributes
"},{"location":"overview/#x","title":"X","text":"XorShift Random - Fast XorShift PRNG \u2192 README - Random Generators | Random Performance
XoroShiro Random - Fast XoroShiro PRNG \u2192 README - Random Generators | Random Performance
See Also:
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.
"},{"location":"overview/getting-started/#core-features","title":"Core Features","text":"Three core principles:
"},{"location":"overview/getting-started/#1-reduced-boilerplate","title":"1. \ud83c\udfaf Reduced Boilerplate","text":"Common APIs:
random.NextWeightedIndex(weights)[SiblingComponent] private Animator animator;Self-documenting code:
C#[SiblingComponent] private Animator animator; // Clear intent\n[ParentComponent(OnlyAncestors = true)] private Rigidbody2D rb; // Explicit search\n[ChildComponent(MaxDepth = 1)] private Collider2D[] colliders; // Limited scope\nError messages:
Speed improvements measured in benchmarks:
Benchmark Results:
Key capabilities:
Jump directly to the solution you need:
Performance Issues?
Workflow Issues?
Architecture Issues?
Full documentation overview (best for team leads and senior developers):
See it working first, understand the theory later:
See the Installation section in the main README for detailed installation instructions using:
.unitypackage from releases, or clone the repositoryAfter installation, verify the package appears in Window \u2192 Package Manager under \"My Registries\" or \"In Project\".
"},{"location":"overview/getting-started/#three-quick-examples","title":"Three Quick Examples","text":""},{"location":"overview/getting-started/#example-1-random-generation-beginner","title":"Example 1: Random Generation (Beginner)","text":"Problem: Unity's UnityEngine.Random is slow and not seedable.
Solution:
C#using WallstopStudios.UnityHelpers.Core.Random;\nusing WallstopStudios.UnityHelpers.Core.Extension;\n\npublic class LootDrop : MonoBehaviour\n{\n void Start()\n {\n // Performance comparison available in benchmarks\n IRandom rng = PRNG.Instance;\n\n // Basic usage\n int damage = rng.Next(10, 20);\n float chance = rng.NextFloat();\n\n // Weighted random selection\n string[] loot = { \"Common\", \"Rare\", \"Epic\", \"Legendary\" };\n float[] weights = { 0.6f, 0.25f, 0.10f, 0.05f };\n int index = rng.NextWeightedIndex(weights);\n Debug.Log($\"Dropped: {loot[index]}\");\n }\n}\n\u26a0\ufe0f 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
"},{"location":"overview/getting-started/#example-2-component-wiring-beginner","title":"Example 2: Component Wiring (Beginner)","text":"Problem: Writing GetComponent calls everywhere is tedious and error-prone.
Solution:
C#using UnityEngine;\nusing WallstopStudios.UnityHelpers.Core.Attributes;\n\npublic class Player : MonoBehaviour\n{\n // Auto-finds SpriteRenderer on same GameObject\n [SiblingComponent]\n private SpriteRenderer spriteRenderer;\n\n // Auto-finds Rigidbody2D in parent hierarchy\n [ParentComponent]\n private Rigidbody2D rigidbody;\n\n // Auto-finds all Collider2D in immediate children only\n [ChildComponent(OnlyDescendants = true, MaxDepth = 1)]\n private Collider2D[] childColliders;\n\n void Awake()\n {\n // One call wires all attributed components\n this.AssignRelationalComponents();\n\n // Now use them\n spriteRenderer.color = Color.red;\n rigidbody.velocity = Vector2.up * 5f;\n Debug.Log($\"Found {childColliders.Length} child colliders\");\n }\n}\n\u26a0\ufe0f Common Mistake: Don't call AssignRelationalComponents() in Update() - it should only run once during initialization (Awake/Start).
Learn More: Relational Components
"},{"location":"overview/getting-started/#using-with-di-containers-vcontainerzenjectreflex","title":"Using With DI Containers (VContainer/Zenject/Reflex)","text":"LifetimeScope.Configure, call builder.RegisterRelationalComponents().RelationalComponentsInstaller to your SceneContext and (optionally) enable the scene scan on initialize.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.Problem: Finding nearby objects with FindObjectsOfType and distance checks is O(n) and slow.
Solution:
C#using WallstopStudios.UnityHelpers.Core.DataStructure;\nusing UnityEngine;\nusing System.Collections.Generic;\n\npublic class EnemyManager : MonoBehaviour\n{\n private QuadTree2D<Enemy> enemyTree;\n private List<Enemy> nearbyBuffer = new(64); // Reusable buffer\n\n void Start()\n {\n // Build tree once (O(n log n))\n Enemy[] enemies = FindObjectsOfType<Enemy>();\n enemyTree = new QuadTree2D<Enemy>(enemies, e => e.transform.position);\n }\n\n public List<Enemy> GetEnemiesNearPlayer(Vector2 playerPos, float radius)\n {\n nearbyBuffer.Clear();\n\n // Fast query: O(log n) instead of O(n)\n enemyTree.GetElementsInRange(playerPos, radius, nearbyBuffer);\n\n return nearbyBuffer;\n }\n}\n\u26a0\ufe0f Common Mistake: Spatial trees are immutable - you must rebuild the tree when enemy positions change. For frequently moving objects, use SpatialHash2D instead.
Learn More:
Based on your needs:
"},{"location":"overview/getting-started/#for-gameplay-programmers","title":"For Gameplay Programmers","text":"Why: Build status effects without writing repetitive code
Use Spatial Trees for AI - Efficient awareness systems
Why: Make enemy AI scale to hundreds of units
Learn Serialization - Save systems and networking
Why: 20+ tools for sprites, animations, validation, and more
Use ScriptableObject Singletons - Global settings management
Why: Auto-created, Odin-compatible config assets
Master Property Drawers - Better inspector workflows
Why: Heaps, tries, sparse sets, and more with clear trade-offs
Use Math Helpers - Avoid common pitfalls
Why: Modulo, geometry, color averaging, and more
Adopt the Buffering Pattern - Zero-allocation queries
Yes! Unity Helpers is:
No! Unity Helpers:
WallstopStudios.UnityHelpers.*)Yes! Unity Helpers is released under the MIT License - use it freely in commercial projects.
"},{"location":"overview/getting-started/#next-steps","title":"Next Steps","text":"Pick one feature that solves your immediate problem:
Your Need Start Here Time to Learn Faster random numbers Random Performance ~5 min Auto-wire components Relational Components ~10 min Spatial queries 2D Spatial Trees ~15 min Buff/debuff system Effects System ~20 min Save/load data Serialization ~20 min Editor automation Editor Tools ~30 min Global settings Singletons ~10 minReady 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.
"},{"location":"overview/getting-started/#related-documentation","title":"\ud83d\udcda Related Documentation","text":"Core Guides:
Deep Dives:
DI Integration:
Need help? Open an issue or check Troubleshooting
"},{"location":"overview/glossary/","title":"Glossary","text":"Quick reference for terms used throughout Unity Helpers documentation.
"},{"location":"overview/glossary/#core-concepts","title":"Core Concepts","text":""},{"location":"overview/glossary/#attribute","title":"Attribute","text":"Buffers<T> or WallstopArrayPool<T>using statements for automatic cleanup[SiblingComponent], [ParentComponent], [ChildComponent][WShowIf], [StringInList], [WReadOnly][ScriptableSingletonPath] attributeT.Instance patternLineHelper.Simplify and SimplifyPreciseWallMath.PositiveMod instead of % operator[ProtoContract] and [ProtoMember(n)] annotationsAxis-Aligned Bounding Box
"},{"location":"overview/glossary/#aot","title":"AOT","text":"Ahead-Of-Time (compilation)
"},{"location":"overview/glossary/#dto","title":"DTO","text":"Data Transfer Object (simple data container for serialization)
"},{"location":"overview/glossary/#fifo","title":"FIFO","text":"First-In-First-Out (queue behavior)
"},{"location":"overview/glossary/#gc","title":"GC","text":"Garbage Collector/Garbage Collection
"},{"location":"overview/glossary/#hdrp","title":"HDRP","text":"High Definition Render Pipeline
"},{"location":"overview/glossary/#knn","title":"kNN","text":"k-Nearest Neighbors
"},{"location":"overview/glossary/#lifo","title":"LIFO","text":"Last-In-First-Out (stack behavior)
"},{"location":"overview/glossary/#mbr","title":"MBR","text":"Minimum Bounding Rectangle
"},{"location":"overview/glossary/#mst","title":"MST","text":"Minimum Spanning Tree
"},{"location":"overview/glossary/#poco","title":"POCO","text":"Plain Old CLR Object (simple class with no framework dependencies)
"},{"location":"overview/glossary/#ppu","title":"PPU","text":"Pixels Per Unit (sprite import setting)
"},{"location":"overview/glossary/#prng","title":"PRNG","text":"Pseudo-Random Number Generator
"},{"location":"overview/glossary/#rng","title":"RNG","text":"Random Number Generator
"},{"location":"overview/glossary/#urp","title":"URP","text":"Universal Render Pipeline
"},{"location":"overview/glossary/#see-also","title":"See Also","text":"This roadmap outlines planned enhancements to Unity Helpers. All \"Currently shipping\" features are production-ready and available now. See the main README for current capabilities.
"},{"location":"overview/roadmap/#1-comprehensive-inspector-tooling","title":"1. Comprehensive Inspector Tooling","text":"Currently shipping: Attribute and property drawer suite covering enum toggles, dropdowns, conditional display, grouping, buttons, and validation. Key attributes: WEnumToggleButtons, WShowIf, WValueDropDown, WGroup, WButton, WNotNull, ValidateAssignment.
Next up:
Currently shipping: Animation Creator, Sprite Sheet Animation Creator, Animation Event Editor, plus 20+ sprite/texture/prefab utilities. See Editor Tools Guide for full list.
Next up:
Currently shipping: 15+ high-quality RNG implementations (IllusionFlow, PcgRandom, XoroShiro, SplitMix64, RomuDuo, FlurryBurst, PhotonSpin, etc.) with extensive IRandom API. See Random Performance.
Next up:
Currently shipping: Production 2D trees (QuadTree2D, KdTree2D, RTree2D, SpatialHash2D) and experimental 3D variants (OctTree3D, KdTree3D, RTree3D, SpatialHash3D). See 2D Performance and 3D Performance.
Next up:
Currently shipping: LayeredImage and MultiFileSelectorElement custom visual elements with samples and persistence helpers.
Next up:
Currently shipping: Extensive utilities covering pooling (Buffers, array pools), singleton patterns, animation helpers, sprite utilities, compression, math extensions, and more. See Helper Utilities.
Next up:
Currently shipping: Comprehensive benchmarks for random generators, spatial trees, reflection helpers, and IList sorting. See Random Performance, Spatial Tree Performance, and Reflection Performance.
Next up:
SerializableNullable<T>.Value access without a preceding HasValue check (Unity asmdef-friendly package)Currently shipping: Data-driven effects system with attributes, tags, effect stacks, and metadata caches. ScriptableObject-driven effect authoring with cosmetics and duration management. See Effects System.
Next up:
Currently shipping: Component auto-wiring attributes (SiblingComponent, ParentComponent, ChildComponent) with DI integrations for VContainer, Zenject, and Reflex. See Relational Components.
Next up:
Auto-generated via PerformanceBaselineTests.GeneratePerformanceBaselineReport. Run the test explicitly to refresh these tables.
These tests serve as automated CI regression guards. They verify that critical operations complete within acceptable time bounds, detecting performance regressions before they reach production.
"},{"location":"performance/baseline-tests-performance/#baseline-philosophy","title":"Baseline Philosophy","text":"Baselines are set generously (2-3x expected typical performance) to account for CI environment variability while still catching significant regressions. A test failure indicates a performance regression that needs investigation.
"},{"location":"performance/baseline-tests-performance/#test-categories","title":"Test Categories","text":"Generated: 2026-01-12 01:36:55 UTC
"},{"location":"performance/baseline-tests-performance/#spatial-trees","title":"Spatial Trees","text":"Test Iterations Time (ms) Baseline (ms) % of Baseline Status QuadTree2DRangeQuery1K2720013.5%Pass QuadTree2DBoundsQuery1K2920014.5%Pass KdTree2DRangeQuery1K2720013.5%Pass KdTree2DNearestNeighbor1K3220016.0%Pass RTree2DRangeQuery1K24792001239.5%FAIL OctTree3DRangeQuery1K152007.5%Pass KdTree3DRangeQuery1K3320016.5%Pass QuadTree2DConstruction125000.4%Pass KdTree2DConstruction125000.4%Pass RTree2DConstruction115000.2%Pass"},{"location":"performance/baseline-tests-performance/#prng","title":"PRNG","text":"Test Iterations Time (ms) Baseline (ms) % of Baseline Status PcgRandomNextInt1M15000.2%Pass PcgRandomNextFloat1M55001.0%Pass XoroShiroRandomNextInt1M15000.2%Pass SplitMix64NextInt1M15000.2%Pass RomuDuoNextInt1M15000.2%Pass"},{"location":"performance/baseline-tests-performance/#pooling","title":"Pooling","text":"Test Iterations Time (ms) Baseline (ms) % of Baseline Status ListPooling100K239504200119752.0%FAIL HashSetPooling100K165032008251.5%FAIL DictionaryPooling100K169972008498.5%FAIL SystemArrayPool100K82004.0%Pass StringBuilderPooling100K164562008228.0%FAIL"},{"location":"performance/baseline-tests-performance/#serialization","title":"Serialization","text":"Test Iterations Time (ms) Baseline (ms) % of Baseline Status JsonSerialize10K435008.6%Pass JsonDeserialize10K6450012.8%Pass JsonRoundTrip10K113100011.3%Pass ProtobufSerialize10K1169500233.8%FAIL ProtobufDeserialize10K125002.4%Pass ProtobufRoundTrip10K17281000172.8%FAIL"},{"location":"performance/baseline-tests-performance/#summary","title":"Summary","text":"19 passed, 7 failed out of 26 tests.
"},{"location":"performance/baseline-tests-performance/#running-the-tests","title":"Running the Tests","text":"These tests run automatically during CI to catch regressions. To generate fresh benchmark results:
PerformanceBaselineTestsGeneratePerformanceBaselineReport explicitly (it is marked [Explicit])Unity Helpers ships several custom sorting algorithms for IList<T> that cover different trade-offs between adaptability, allocation patterns, and stability. This page gathers context and benchmark snapshots so you can choose the right algorithm for your workload and compare results across operating systems.
What does \u201cstable\u201d mean? Stable sorting algorithms preserve the relative order of elements that compare as equal. This matters when items carry secondary keys (e.g., sorting people by last name but keeping first-name order deterministic). Unstable algorithms can reshuffle equal entries, which is usually fine for numeric keys but can break deterministic pipelines.
Heads up: The original Ghost Sort repository was formerly hosted on GitHub under wstaffordp/ghostsort, but it currently returns 404. The Unity Helpers implementation remains based on that source; we will relink if/when an official mirror returns.
Each benchmark sorts a fresh copy of the dataset once and reports wall-clock duration. If a cell still shows pending, re-run the benchmark suite to collect fresh data for that algorithm/dataset size.
Run the IListSortingPerformanceTests.Benchmark test inside Unity\u2019s Test Runner to refresh the tables below. Results automatically land in the section that matches the current operating system.
Last updated 2026-01-12 01:17 UTC on Windows 11 (10.0.26200) 64bit
Times are single-pass measurements in milliseconds (lower is better). n/a indicates the algorithm was skipped for the dataset size.
Pending \u2014 run the IList sorting benchmark suite on macOS to capture results.
"},{"location":"performance/ilist-sorting-performance/#linux","title":"Linux","text":"Pending \u2014 run the IList sorting benchmark suite on Linux to capture results.
"},{"location":"performance/ilist-sorting-performance/#other-platforms","title":"Other Platforms","text":"Pending \u2014 run the IList sorting benchmark suite on the target platform to capture results.
"},{"location":"performance/random-performance/","title":"Random Number Generator Performance Benchmarks","text":"Auto-generated via RandomPerformanceTests.Benchmark. Run the test to refresh these summary and detail tables.
"},{"location":"performance/random-performance/#summary-fastest-first","title":"Summary (fastest first)","text":"Random NextUint (ops/s) Speed Quality Notes LinearCongruentialGenerator1,333,700,000FastestPoorMinimal standard LCG; fails spectral tests and exhibits lattice artifacts beyond small dimensions. WaveSplatRandom1,323,500,000FastestExperimentalSingle-word chaotic generator; author notes period 2^64 but provides no formal test results\u2014treat as experimental. BlastCircuitRandom1,068,900,000Very FastGoodEmpirical PractRand testing to 32GB shows strong diffusion; designed as a chaotic ARX mixer rather than a proven statistically optimal generator. SplitMix641,042,200,000Very FastVery GoodWell-known SplitMix64 mixer; passes TestU01 BigCrush and PractRand up to large data sizes in literature. Steele, Lea, Flood 2014 FlurryBurstRandom947,500,000FastExcellentSix-word ARX-style generator tuned for all-around use; passes TestU01 BigCrush per upstream reference implementation. Will Stafford Parsons (wileylooper) PcgRandom916,300,000FastExcellentPCG XSH RR 64/32 variant; passes TestU01 BigCrush and PractRand in published results. O'Neill 2014 IllusionFlow891,400,000FastExcellentHybridized PCG + xorshift design; upstream PractRand 64GB passes with no anomalies per author. XoroShiroRandom762,900,000FastVery Goodxoshiro128** variant; authors recommend for general-purpose use and report clean BigCrush performance with jump functions. Blackman & Vigna 2018 RomuDuo757,900,000FastVery GoodROMU family member (RomuDuo); authors report strong BigCrush results with minor low-bit weaknesses in some rotations. StormDropRandom713,500,000ModerateExcellent20-word ARX generator derived from SHISHUA; author reports excellent PractRand performance and long periods. XorShiftRandom599,800,000ModerateFairClassic 32-bit xorshift; known to fail portions of TestU01 and PractRand, acceptable for lightweight effects only. Marsaglia 2003 WyRandom440,100,000SlowVery GoodWyhash-based generator; published testing shows it clears BigCrush/PractRand with wide seed coverage. Wang Yi 2019 SquirrelRandom409,000,000SlowGoodHash-based generator built on Squirrel3; good equidistribution for table lookups but not extensively tested beyond moderate ranges. Squirrel Eiserloh PhotonSpinRandom260,200,000Very SlowExcellentSHISHUA-inspired generator; independent testing (PractRand 128GB) by author indicates excellent distribution properties. UnityRandom86,800,000Very SlowFairMirrors UnityEngine.Random (Xorshift196 + additive); suitable for legacy compatibility but not high-stakes simulation. Unity Random Internals SystemRandom64,200,000Very SlowPoorThin wrapper over System.Random; inherits same LCG weaknesses and fails modern statistical batteries. System.Random considered harmful DotNetRandom54,300,000Very SlowPoorLinear congruential generator (mod 2^31) with known correlation failures; unsuitable for high-quality simulations. System.Random considered harmful"},{"location":"performance/random-performance/#detailed-metrics","title":"Detailed Metrics","text":"Random NextBool Next NextUint NextFloat NextDouble NextUint (Range) NextInt (Range) LinearCongruentialGenerator812,500,000844,800,0001,333,700,000184,600,000387,000,000580,800,000505,400,000 WaveSplatRandom780,800,000721,900,0001,323,500,000182,500,000400,700,000532,600,000463,400,000 BlastCircuitRandom785,700,000716,200,0001,068,900,000183,300,000353,100,000485,400,000422,600,000 SplitMix64777,700,000774,200,0001,042,200,000183,200,000362,300,000484,000,000436,100,000 FlurryBurstRandom771,200,000678,400,000947,500,000183,500,000311,600,000445,700,000405,200,000 PcgRandom777,500,000673,700,000916,300,000184,200,000328,700,000454,100,000409,400,000 IllusionFlow789,200,000641,300,000891,400,000177,800,000309,100,000445,700,000396,000,000 XoroShiroRandom770,000,000592,300,000762,900,000165,800,000242,400,000427,700,000381,800,000 RomuDuo783,100,000592,000,000757,900,000164,500,000249,800,000443,500,000394,800,000 StormDropRandom776,100,000568,200,000713,500,000181,400,000264,100,000397,600,000364,300,000 XorShiftRandom779,800,000587,300,000599,800,000183,300,000272,400,000432,200,000388,700,000 WyRandom749,900,000380,600,000440,100,000164,700,000186,700,000293,600,000274,300,000 SquirrelRandom759,200,000407,200,000409,000,000169,500,000193,400,000331,400,000311,200,000 PhotonSpinRandom701,900,000246,500,000260,200,000118,000,000117,000,000211,300,000204,300,000 UnityRandom623,500,00084,100,00086,800,00061,200,00041,000,00080,400,00081,400,000 SystemRandom147,100,000148,100,00064,200,000130,900,000137,700,00058,500,00056,900,000 DotNetRandom539,800,00052,500,00054,300,00045,800,00026,700,00053,500,00053,000,000"},{"location":"performance/reflection-performance/","title":"Reflection Performance Benchmarks","text":"Unity Helpers replaces ad-hoc reflection with cached delegates that favour expression lambdas on IL2CPP-safe platforms and fall back to dynamic IL emit or plain reflection where available. These benchmarks compare raw System.Reflection against the helpers for common access patterns.
Each run updates the table for the current operating system only. Sections that still show _No benchmark data generated yet._ simply have not been executed on that platform.
Generated on 2026-01-12 01:50:03 UTC
"},{"location":"performance/reflection-performance/#strategy-default-auto","title":"Strategy: Default (auto)","text":""},{"location":"performance/reflection-performance/#boxed-access-object","title":"Boxed Access (object)","text":"Scenario Helper (ops/sec) System.Reflection (ops/sec) Speedup vs Reflection Instance Field Get (boxed)25.21M6.69M3.77x Instance Field Set (boxed)22.18M5.50M4.03x Static Field Get (boxed)16.53M2.71M6.09x Static Field Set (boxed)18.01M4.92M3.66x Instance Property Get (boxed)28.85M25.19M1.15x Instance Property Set (boxed)24.78M1.49M16.61x Static Property Get (boxed)21.82M24.49M0.89x Static Property Set (boxed)26.46M2.54M10.42x Instance Method Invoke (boxed)20.55M1.71M11.99x Static Method Invoke (boxed)25.30M2.68M9.42x Constructor Invoke (boxed)23.48M2.52M9.33x"},{"location":"performance/reflection-performance/#typed-access-no-boxing","title":"Typed Access (no boxing)","text":"Scenario Helper (ops/sec) Baseline Delegate (ops/sec) System.Reflection (ops/sec) Speedup vs Delegate Speedup vs Reflection Instance Field Get (typed)650.81M661.45M6.69M0.98x97.25x Instance Field Set (typed)653.34M660.94M5.50M0.99x118.80x Static Field Get (typed)663.07M687.03M2.71M0.97x244.39x Static Field Set (typed)681.63M670.11M4.92M1.02x138.44x Instance Property Get (typed)685.44M692.09M25.19M0.99x27.21x Instance Property Set (typed)661.24M701.70M1.49M0.94x443.26x Static Property Get (typed)652.49M685.16M24.49M0.95x26.64x Static Property Set (typed)677.05M657.03M2.54M1.03x266.65x Instance Method Invoke (typed)686.13M685.59M1.71M1.00x400.58x Static Method Invoke (typed)659.66M678.18M2.68M0.97x245.75x"},{"location":"performance/reflection-performance/#strategy-expressions","title":"Strategy: Expressions","text":""},{"location":"performance/reflection-performance/#boxed-access-object_1","title":"Boxed Access (object)","text":"Scenario Helper (ops/sec) System.Reflection (ops/sec) Speedup vs Reflection Instance Field Get (boxed)24.78M6.08M4.07x Instance Field Set (boxed)28.58M5.48M5.21x Static Field Get (boxed)20.95M8.51M2.46x Static Field Set (boxed)27.73M4.57M6.06x Instance Property Get (boxed)21.15M3.49M6.06x Instance Property Set (boxed)12.82M2.02M6.34x Static Property Get (boxed)22.50M20.45M1.10x Static Property Set (boxed)20.66M2.88M7.17x Instance Method Invoke (boxed)23.90M1.98M12.08x Static Method Invoke (boxed)27.12M2.21M12.27x Constructor Invoke (boxed)27.01M2.54M10.65x"},{"location":"performance/reflection-performance/#typed-access-no-boxing_1","title":"Typed Access (no boxing)","text":"Scenario Helper (ops/sec) Baseline Delegate (ops/sec) System.Reflection (ops/sec) Speedup vs Delegate Speedup vs Reflection Instance Field Get (typed)692.43M658.49M6.08M1.05x113.81x Instance Field Set (typed)651.66M657.97M5.48M0.99x118.84x Static Field Get (typed)647.30M683.07M8.51M0.95x76.02x Static Field Set (typed)669.78M656.50M4.57M1.02x146.40x Instance Property Get (typed)676.92M684.18M3.49M0.99x194.03x Instance Property Set (typed)657.90M691.31M2.02M0.95x325.26x Static Property Get (typed)643.98M684.71M20.45M0.94x31.49x Static Property Set (typed)669.72M653.78M2.88M1.02x232.38x Instance Method Invoke (typed)680.33M680.42M1.98M1.00x343.95x Static Method Invoke (typed)653.83M674.42M2.21M0.97x295.69x"},{"location":"performance/reflection-performance/#strategy-dynamic-il","title":"Strategy: Dynamic IL","text":""},{"location":"performance/reflection-performance/#boxed-access-object_2","title":"Boxed Access (object)","text":"Scenario Helper (ops/sec) System.Reflection (ops/sec) Speedup vs Reflection Instance Field Get (boxed)27.70M5.80M4.77x Instance Field Set (boxed)28.24M5.45M5.18x Static Field Get (boxed)21.57M8.41M2.56x Static Field Set (boxed)25.65M6.16M4.17x Instance Property Get (boxed)18.83M22.95M0.82x Instance Property Set (boxed)25.31M1.98M12.80x Static Property Get (boxed)23.51M8.69M2.71x Static Property Set (boxed)2.06M2.86M0.72x Instance Method Invoke (boxed)23.09M2.00M11.56x Static Method Invoke (boxed)27.05M2.12M12.75x Constructor Invoke (boxed)26.10M2.52M10.36x"},{"location":"performance/reflection-performance/#typed-access-no-boxing_2","title":"Typed Access (no boxing)","text":"Scenario Helper (ops/sec) Baseline Delegate (ops/sec) System.Reflection (ops/sec) Speedup vs Delegate Speedup vs Reflection Instance Field Get (typed)662.00M685.29M5.80M0.97x114.09x Instance Field Set (typed)654.77M661.50M5.45M0.99x120.17x Static Field Get (typed)657.70M683.29M8.41M0.96x78.17x Static Field Set (typed)675.09M659.39M6.16M1.02x109.61x Instance Property Get (typed)673.39M690.30M22.95M0.98x29.34x Instance Property Set (typed)652.07M693.53M1.98M0.94x329.72x Static Property Get (typed)648.59M682.82M8.69M0.95x74.63x Static Property Set (typed)671.01M654.32M2.86M1.03x234.23x Instance Method Invoke (typed)690.97M686.98M2.00M1.01x345.91x Static Method Invoke (typed)660.09M679.79M2.12M0.97x311.08x"},{"location":"performance/reflection-performance/#strategy-reflection-fallback","title":"Strategy: Reflection Fallback","text":""},{"location":"performance/reflection-performance/#boxed-access-object_3","title":"Boxed Access (object)","text":"Scenario Helper (ops/sec) System.Reflection (ops/sec) Speedup vs Reflection Instance Field Get (boxed)7.48M5.76M1.30x Instance Field Set (boxed)5.57M5.47M1.02x Static Field Get (boxed)7.71M7.19M1.07x Static Field Set (boxed)6.01M6.13M0.98x Instance Property Get (boxed)21.09M18.38M1.15x Instance Property Set (boxed)2.09M2.06M1.01x Static Property Get (boxed)20.07M23.51M0.85x Static Property Set (boxed)2.88M2.02M1.42x Instance Method Invoke (boxed)1.99M1.98M1.01x Static Method Invoke (boxed)2.69M2.72M0.99x Constructor Invoke (boxed)2.55M2.50M1.02x"},{"location":"performance/reflection-performance/#typed-access-no-boxing_3","title":"Typed Access (no boxing)","text":"Scenario Helper (ops/sec) Baseline Delegate (ops/sec) System.Reflection (ops/sec) Speedup vs Delegate Speedup vs Reflection Instance Field Get (typed)5.24M662.95M5.76M0.01x0.91x Instance Field Set (typed)5.46M668.23M5.47M0.01x1.00x Static Field Get (typed)8.64M683.37M7.19M0.01x1.20x Static Field Set (typed)4.77M661.19M6.13M0.01x0.78x Instance Property Get (typed)675.25M683.53M18.38M0.99x36.75x Instance Property Set (typed)655.22M704.28M2.06M0.93x317.56x Static Property Get (typed)652.21M691.83M23.51M0.94x27.75x Static Property Set (typed)678.92M659.94M2.02M1.03x335.95x Instance Method Invoke (typed)692.36M685.00M1.98M1.01x350.50x Static Method Invoke (typed)661.40M678.90M2.72M0.97x242.98x"},{"location":"performance/reflection-performance/#macos","title":"macOS","text":"No benchmark data generated yet.
"},{"location":"performance/reflection-performance/#linux","title":"Linux","text":"No benchmark data generated yet.
"},{"location":"performance/reflection-performance/#unknown-other","title":"Unknown / Other","text":"No benchmark data generated yet.
"},{"location":"performance/relational-components-performance/","title":"Relational Component Performance Benchmarks","text":"Relational component attributes ([SiblingComponent], [ParentComponent], [ChildComponent]) remove repetitive GetComponent* code. These benchmarks quantify the runtime cost of calling Assign*Components for common field shapes (single component, array, List<T>, and HashSet<T>) against hand-written lookups.
How to refresh these tables:
RelationalComponentBenchmarkTests.Benchmark inside Tests/Runtime/Performance.The script executes the benchmark test in batch mode, captures the markdown tables to BenchmarkLogs/RelationalBenchmark.log, and preserves the raw TestResults.xml when -KeepResults is specified.
Last updated 2026-01-12 01:51 UTC on Windows 11 (10.0.26200) 64bit
Numbers capture repeated Assign*Components calls for one second per scenario. Higher operations per second are better.
Pending \u2014 run the relational component benchmark suite on macOS to capture results.
"},{"location":"performance/relational-components-performance/#linux","title":"Linux","text":"Pending \u2014 run the relational component benchmark suite on Linux to capture results.
"},{"location":"performance/relational-components-performance/#other-platforms","title":"Other Platforms","text":"Pending \u2014 run the relational component benchmark suite on the target platform to capture results.
"},{"location":"performance/spatial-tree-2d-performance/","title":"2D Spatial Tree Performance Benchmarks","text":""},{"location":"performance/spatial-tree-2d-performance/#tldr-what-problem-this-solves","title":"TL;DR \u2014 What Problem This Solves","text":"This document contains performance benchmarks for the 2D spatial tree implementations in Unity Helpers.
"},{"location":"performance/spatial-tree-2d-performance/#available-2d-spatial-trees","title":"Available 2D Spatial Trees","text":"All numbers represent operations per second (higher is better), except for construction times which show operations per second and absolute time.
"},{"location":"performance/spatial-tree-2d-performance/#choosing-the-right-tree","title":"Choosing the Right Tree","text":"QuadTree2D:
KdTree2D (Balanced):
KdTree2D (Unbalanced):
RTree2D:
Note: KdTree3D, OctTree3D, and RTree3D are under active development and their APIs/performance may evolve. SpatialHash3D is stable and recommended for broad\u2011phase neighbor queries with many moving objects.
For boundary and result semantics across structures, see Spatial Tree Semantics
This document contains performance benchmarks for the 3D spatial tree implementations in Unity Helpers.
"},{"location":"performance/spatial-tree-3d-performance/#available-3d-spatial-trees","title":"Available 3D Spatial Trees","text":"All numbers represent operations per second (higher is better), except for construction times which show operations per second and absolute time.
"},{"location":"performance/spatial-tree-3d-performance/#choosing-the-right-tree","title":"Choosing the Right Tree","text":"OctTree3D:
KdTree3D (Balanced):
KdTree3D (Unbalanced):
RTree3D:
Thanks for helping make Unity Helpers better! This project uses a few automated checks and formatters to keep the codebase consistent and easy to review.
"},{"location":"project/contributing/#dev-container-setup-recommended","title":"Dev Container Setup (Recommended)","text":"The easiest way to contribute is using the included dev container, which has all CI/CD tools pre-installed:
npm run verify:tools to confirm all tools are availableThe dev container includes these additional tools that are not required on your host machine. Git hooks gracefully skip them if not present\u2014CI will catch any issues:
These tools are required and installed via npm/dotnet:
_llm_ are git-ignored and automatically removed from the Unity package during imports.Dependabot PRs are auto-formatted by CI. The bot pushes commits (same\u2011repo PRs) or opens a formatting PR (forked PRs) so they pass formatting gates.
"},{"location":"project/contributing/#optin-formatting-for-contributor-prs","title":"Opt\u2011In Formatting for Contributor PRs","text":"If you want the bot to apply formatting to your PR:
/format (aliases: /autofix, /lint-fix).What gets auto\u2011fixed:
--fixWhat does not auto\u2011fix:
npm ci (or npm i --no-audit --no-fund)dotnet tool restorenpm run verify:toolsdotnet tool run csharpier formatnpm run validate:contentnpm run eol:checkactionlintnpm run lint:doc-links (cross-platform wrapper that locates PowerShell automatically)scripts/run-doc-link-lint.js so you can also run node ./scripts/run-doc-link-lint.js --verbose if you are not using npm scripts.docs/... references inside source files or scripts. The lint-doc-links GitHub Actions workflow runs it on every PR, so run it locally before pushing large doc updates.Please follow the conventions outlined in .editorconfig and the repository guidelines (PascalCase types, camelCase fields, explicit types, braces required, no regions).
This project follows Semantic Versioning. Key points:
3.1.5 (no v prefix)v prefix (e.g., v3.1.5) for visual consistency, synced automatically via pre-commit hookWhen installing via Git URL, reference versions without the v prefix:
https://github.com/wallstop/unity-helpers.git#3.1.5\nReleases are drafted automatically via release-drafter. Maintainers review and publish the draft when ready.
"},{"location":"project/license/","title":"License","text":"This project is licensed under the MIT License.
See the full license text in the repository root: LICENSE
"},{"location":"project/llms-txt/","title":"llms.txt - LLM-Friendly Documentation","text":"Unity Helpers includes an llms.txt file following the llmstxt.org specification. This file provides structured, LLM-optimized documentation that enables AI assistants to quickly understand and work with the package.
The llms.txt specification defines a standard format for providing LLM-friendly content. Unlike full HTML documentation that may be too large for context windows, llms.txt offers:
The file is located at the repository root: /llms.txt
The Unity Helpers llms.txt includes:
AI assistants and LLM-powered tools can:
https://raw.githubusercontent.com/wallstop/unity-helpers/main/llms.txtIf you're an AI assistant working with this repository, you can also reference:
This file provides additional context about coding style, testing patterns, and repository-specific conventions.
"},{"location":"project/llms-txt/#related","title":"Related","text":"This package contains third-party software components governed by the license(s) indicated below.
"},{"location":"project/third-party-notices/#serialization-compression","title":"Serialization & Compression","text":""},{"location":"project/third-party-notices/#protobuf-net","title":"protobuf-net","text":"ProtoBuf.Serializer.SevenZip.Compression.LZMA.Runtime/Utils/SevenZip/Compress/LZMA.WInLineEditorDrawer build upon concepts from the toolbox's InlineEditor drawer implementation.The following sorting algorithm implementations in Runtime/Core/Extension/IListExtensions.cs are adapted from or inspired by third-party sources.
IList<T>.The following PRNG implementations in Runtime/Core/Random/ are adapted from or inspired by third-party sources.
The following algorithms are by Will Stafford Parsons (wileylooper). Note: The original GitHub repositories are currently offline.
License: These implementations are used with attribution to the original author. Please refer to the individual repositories for specific licensing terms if they become available again.
"},{"location":"project/third-party-notices/#academic-historical-acknowledgments","title":"Academic & Historical Acknowledgments","text":"The following algorithms are based on well-known academic work and are implemented from published descriptions:
"},{"location":"project/third-party-notices/#sorting-algorithms_1","title":"Sorting Algorithms","text":"Used by: Unity-Serializable-Dictionary, Unity Editor Toolbox, Grail Sort, cocowalla/wyhash-dotnet
Text OnlyMIT License\n\nCopyright (c) [year] [copyright holders]\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\nUsed by: protobuf-net, PCG Random, sort-research-rs algorithms
Text OnlyApache License\nVersion 2.0, January 2004\nhttps://www.apache.org/licenses/\n\nTERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n1. Definitions.\n \"License\" shall mean the terms and conditions for use, reproduction, and\n distribution as defined by Sections 1 through 9 of this document.\n \"Licensor\" shall mean the copyright owner or entity authorized by the\n copyright owner that is granting the License.\n \"Legal Entity\" shall mean the union of the acting entity and all other\n entities that control, are controlled by, or are under common control with\n that entity.\n \"You\" (or \"Your\") shall mean an individual or Legal Entity exercising\n permissions granted by this License.\n \"Source\" form shall mean the preferred form for making modifications,\n including but not limited to software source code, documentation source,\n and configuration files.\n \"Object\" form shall mean any form resulting from mechanical transformation\n or translation of a Source form, including but not limited to compiled\n object code, generated documentation, and conversions to other media types.\n \"Work\" shall mean the work of authorship, whether in Source or Object form,\n made available under the License, as indicated by a copyright notice that\n is included in or attached to the work.\n \"Derivative Works\" shall mean any work, whether in Source or Object form,\n that is based on (or derived from) the Work and for which the editorial\n revisions, annotations, elaborations, or other modifications represent, as\n a whole, an original work of authorship.\n \"Contribution\" shall mean any work of authorship, including the original\n version of the Work and any modifications or additions to that Work or\n Derivative Works thereof, that is intentionally submitted to Licensor for\n inclusion in the Work by the copyright owner or by an individual or Legal\n Entity authorized to submit on behalf of the copyright owner.\n \"Contributor\" shall mean Licensor and any individual or Legal Entity on\n behalf of whom a Contribution has been received by Licensor and\n subsequently incorporated within the Work.\n\n2. Grant of Copyright License.\n Subject to the terms and conditions of this License, each Contributor\n hereby grants to You a perpetual, worldwide, non-exclusive, no-charge,\n royalty-free, irrevocable copyright license to reproduce, prepare\n Derivative Works of, publicly display, publicly perform, sublicense, and\n distribute the Work and such Derivative Works in Source or Object form.\n\n3. Grant of Patent License.\n Subject to the terms and conditions of this License, each Contributor\n hereby grants to You a perpetual, worldwide, non-exclusive, no-charge,\n royalty-free, irrevocable (except as stated in this section) patent license\n to make, have made, use, offer to sell, sell, import, and otherwise\n transfer the Work.\n\n4. Redistribution.\n You may reproduce and distribute copies of the Work or Derivative Works\n thereof in any medium, with or without modifications, and in Source or\n Object form, provided that You meet the following conditions:\n (a) You must give any other recipients of the Work or Derivative Works a\n copy of this License; and\n (b) You must cause any modified files to carry prominent notices stating\n that You changed the files; and\n (c) You must retain, in the Source form of any Derivative Works that You\n distribute, all copyright, patent, trademark, and attribution notices\n from the Source form of the Work; and\n (d) If the Work includes a \"NOTICE\" text file as part of its distribution,\n then any Derivative Works that You distribute must include a readable\n copy of the attribution notices contained within such NOTICE file,\n excluding those notices that do not pertain to any part of the\n Derivative Works.\n\n5. Submission of Contributions.\n Unless You explicitly state otherwise, any Contribution intentionally\n submitted for inclusion in the Work by You to the Licensor shall be under\n the terms and conditions of this License, without any additional terms or\n conditions.\n\n6. Trademarks.\n This License does not grant permission to use the trade names, trademarks,\n service marks, or product names of the Licensor, except as required for\n reasonable and customary use in describing the origin of the Work and\n reproducing the content of the NOTICE file.\n\n7. Disclaimer of Warranty.\n Unless required by applicable law or agreed to in writing, Licensor\n provides the Work (and each Contributor provides its Contributions) on an\n \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express\n or implied.\n\n8. Limitation of Liability.\n In no event and under no legal theory, whether in tort (including\n negligence), contract, or otherwise, unless required by applicable law\n (such as deliberate and grossly negligent acts) or agreed to in writing,\n shall any Contributor be liable to You for damages, including any direct,\n indirect, special, incidental, or consequential damages of any character\n arising as a result of this License or out of the use or inability to use\n the Work.\n\n9. Accepting Warranty or Additional Liability.\n While redistributing the Work or Derivative Works thereof, You may choose\n to offer, and charge a fee for, acceptance of support, warranty, indemnity,\n or other liability obligations and/or rights consistent with this License.\n\nEND OF TERMS AND CONDITIONS\nUsed by: pdqsort
Text Onlyzlib License\n\nCopyright (c) [year] [copyright holders]\n\nThis software is provided 'as-is', without any express or implied warranty.\nIn no event will the authors be held liable for any damages arising from the\nuse of this software.\n\nPermission is granted to anyone to use this software for any purpose,\nincluding commercial applications, and to alter it and redistribute it\nfreely, subject to the following restrictions:\n\n1. The origin of this software must not be misrepresented; you must not claim\n that you wrote the original software. If you use this software in a\n product, an acknowledgment in the product documentation would be\n appreciated but is not required.\n\n2. Altered source versions must be plainly marked as such, and must not be\n misrepresented as being the original software.\n\n3. This notice may not be removed or altered from any source distribution.\nUsed by: Xoroshiro/Xoshiro/SplitMix64, RomuDuo
Text OnlyCC0 1.0 Universal\n\nCREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE LEGAL\nSERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN ATTORNEY-CLIENT\nRELATIONSHIP. CREATIVE COMMONS PROVIDES THIS INFORMATION ON AN \"AS-IS\" BASIS.\nCREATIVE COMMONS MAKES NO WARRANTIES REGARDING THE USE OF THIS DOCUMENT OR\nTHE INFORMATION OR WORKS PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR\nDAMAGES RESULTING FROM THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS\nPROVIDED HEREUNDER.\n\nStatement of Purpose\n\nThe laws of most jurisdictions throughout the world automatically confer\nexclusive Copyright and Related Rights (defined below) upon the creator and\nsubsequent owner(s) (each and all, an \"owner\") of an original work of\nauthorship and/or a database (each, a \"Work\").\n\nCertain owners wish to permanently relinquish those rights to a Work for the\npurpose of contributing to a commons of creative, cultural and scientific\nworks (\"Commons\") that the public can reliably and without fear of later\nclaims of infringement build upon, modify, incorporate in other works, reuse\nand redistribute as freely as possible in any form whatsoever and for any\npurposes, including without limitation commercial purposes.\n\nThe person associating CC0 with a Work (the \"Affirmer\"), to the extent that\nhe or she is an owner of Copyright and Related Rights in the Work, voluntarily\nelects to apply CC0 to the Work and publicly distribute the Work under its\nterms, with knowledge of his or her Copyright and Related Rights in the Work\nand the meaning and intended legal effect of CC0 on those rights.\n\n1. Copyright and Related Rights.\n A Work made available under CC0 may be protected by copyright and related\n or neighboring rights (\"Copyright and Related Rights\").\n\n2. Waiver.\n To the greatest extent permitted by, but not in contravention of,\n applicable law, Affirmer hereby overtly, fully, permanently, irrevocably\n and unconditionally waives, abandons, and surrenders all of Affirmer's\n Copyright and Related Rights and associated claims and causes of action.\n\n3. Public License Fallback.\n Should any part of the Waiver for any reason be judged legally invalid or\n ineffective under applicable law, then the Waiver shall be preserved to\n the maximum extent permitted. In addition, to the extent the Waiver is so\n judged Affirmer hereby grants to each affected person a royalty-free, non\n transferable, non sublicensable, non exclusive, irrevocable and\n unconditional license to exercise Affirmer's Copyright and Related Rights\n in the Work.\n\n4. Limitations and Disclaimers.\n a. No trademark or patent rights held by Affirmer are waived, abandoned,\n surrendered, licensed or otherwise affected by this document.\n b. Affirmer offers the Work as-is and makes no representations or\n warranties of any kind concerning the Work.\n c. Affirmer disclaims responsibility for clearing rights of other persons\n that may apply to the Work.\n d. Affirmer understands and acknowledges that Creative Commons is not a\n party to this document and has no duty or obligation with respect to\n this CC0 or use of the Work.\nUsed by: wyhash
Text OnlyThis is free and unencumbered software released into the public domain.\n\nAnyone is free to copy, modify, publish, use, compile, sell, or distribute\nthis software, either in source code form or as a compiled binary, for any\npurpose, commercial or non-commercial, and by any means.\n\nIn jurisdictions that recognize copyright laws, the author or authors of this\nsoftware dedicate any and all copyright interest in the software to the\npublic domain. We make this dedication for the benefit of the public at large\nand to the detriment of our heirs and successors. We intend this dedication\nto be an overt act of relinquishment in perpetuity of all present and future\nrights to this software under copyright law.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN\nACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION\nWITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\nFor more information, please refer to <https://unlicense.org>\n