Skip to content

Commit f0213bc

Browse files
wallstopCopilot
andauthored
Less LLM-ified Documentation (#170)
## Description Toned down the self-congratulatory tone throughout the repo ## Related Issue <!-- Link to the issue this PR addresses --> Fixes # ## Type of Change <!-- Check all that apply --> - [ ] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [x] Documentation update - [ ] Refactor (code change that neither fixes a bug nor adds a feature) ## Checklist <!-- Ensure all items are completed before requesting review --> - [ ] I have added tests that prove my fix is effective or my feature works - [x] I have updated the documentation accordingly - [ ] I have updated the [CHANGELOG](../CHANGELOG.md) - [x] My changes do not introduce breaking changes, or breaking changes are documented --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent 7882fe4 commit f0213bc

File tree

14 files changed

+617
-244
lines changed

14 files changed

+617
-244
lines changed

.llm/context.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ Invoke these skills for specific tasks.
8383
**Regenerate with**: `pwsh -NoProfile -File scripts/generate-skills-index.ps1`
8484

8585
<!-- BEGIN GENERATED SKILLS INDEX -->
86-
<!-- Generated: 2026-01-21 11:38:27 UTC -->
86+
<!-- Generated: 2026-01-24 15:34:43 UTC -->
8787
<!-- Command: pwsh -NoProfile -File scripts/generate-skills-index.ps1 -->
8888

8989
### Core Skills (Always Consider)
@@ -101,6 +101,7 @@ Invoke these skills for specific tasks.
101101
| [create-unity-meta](./skills/create-unity-meta.md) | After creating ANY new file or folder |
102102
| [defensive-editor-programming](./skills/defensive-editor-programming.md) | Editor code - handle Unity Editor edge cases |
103103
| [defensive-programming](./skills/defensive-programming.md) | ALL code - never throw, handle gracefully |
104+
| [documentation-consistency](./skills/documentation-consistency.md) | When writing or reviewing documentation |
104105
| [editor-caching-patterns](./skills/editor-caching-patterns.md) | Caching strategies for Editor code |
105106
| [formatting](./skills/formatting.md) | After ANY file change (CSharpier/Prettier) |
106107
| [git-hook-patterns](./skills/git-hook-patterns.md) | Pre-commit hook safety and configuration |

.llm/skills/documentation-consistency.md

Lines changed: 381 additions & 0 deletions
Large diffs are not rendered by default.

.llm/skills/update-documentation.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -342,6 +342,7 @@ The following skills involve customer-visible changes and MUST be followed by do
342342

343343
## Related Skills
344344

345+
- [documentation-consistency](./documentation-consistency.md) — Performance claims, time estimates, emoji prefixes, bullet lists
345346
- [markdown-reference](./markdown-reference.md) — Link formatting, escaping, linting rules
346347
- [validate-before-commit](./validate-before-commit.md) — Pre-commit validation workflow
347348
- [create-csharp-file](./create-csharp-file.md) — New files need XML docs

README.md

Lines changed: 38 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -33,9 +33,9 @@
3333
<a href="https://github.com/wallstop/unity-helpers/releases"><img alt="GitHub downloads" src="https://img.shields.io/github/downloads/wallstop/unity-helpers/total" /></a>
3434
</p>
3535

36-
**Stop writing boilerplate. Start shipping features.**
36+
**Reduce time spent on boilerplate and focus more on features.**
3737

38-
Unity Helpers eliminates entire categories of repetitive work with production-ready utilities that are 10-100x faster than writing it yourself. From auto-wiring components to blazing-fast spatial queries, this is the toolkit that pays for itself in the first hour.
38+
Unity Helpers provides production-ready utilities designed to improve development speed. Key performance highlights: 10-15x faster random generation than Unity.Random (see benchmarks), O(log n) spatial queries, and declarative inspector attributes to reduce custom editor code.
3939

4040
---
4141

@@ -54,9 +54,9 @@ Unity Helpers eliminates entire categories of repetitive work with production-re
5454

5555
**What makes this different:**
5656

57-
- 🎨 **Professional inspector tooling** - Grouping, buttons, conditional display, toggle grids (consider as an Odin alternative) — [Migration Guide](./docs/guides/odin-migration-guide.md)
58-
-**10-15x faster** random generation than Unity.Random
59-
- 🔌 **Zero boilerplate** component wiring with attributes
57+
- 🎨 **Inspector tooling** Grouping, buttons, conditional display, toggle grids. Covers common use cases similar to Odin Inspector; for advanced scenarios, see the [feature comparison](./docs/guides/odin-migration-guide.md)
58+
-**10-15x faster** random generation than Unity.Random in benchmarks (see performance docs for details)
59+
- 🔌 **Reduced boilerplate** component wiring with attributes
6060
- 🎮 **Designer-friendly** effects system (buffs/debuffs as ScriptableObjects)
6161
- 🌳 **O(log n)** spatial queries instead of O(n) loops
6262
- 🛠️ **20+ editor tools** that automate sprite/animation workflows
@@ -90,29 +90,27 @@ Unity Helpers eliminates entire categories of repetitive work with production-re
9090

9191
**Pick your starting point based on your biggest pain point:**
9292

93-
| Your Problem | Your Solution | Time to Value |
94-
| ------------------------------------ | --------------------------------------------------------------------------------------- | ------------- |
95-
| 🎨 Writing custom editors | [**Inspector Tooling**](#1--professional-inspector-tooling) - Odin-level features, FREE | 2 minutes |
96-
| 🐌 Writing `GetComponent` everywhere | [**Relational Components**](#2--auto-wire-components) - Auto-wire with attributes | 2 minutes |
97-
| 🎮 Need buffs/debuffs system | [**Effects System**](#3--data-driven-effects) - Designer-friendly ScriptableObjects | 5 minutes |
98-
| 🔍 Slow spatial searches | [**Spatial Trees**](#spatial-trees) - O(log n) queries | 5 minutes |
99-
| 🎲 Random is too slow/limited | [**PRNG.Instance**](#random-number-generators) - 10-15x faster, extensive API | 1 minute |
100-
| 💾 Need save/load system | [**Serialization**](#4--unity-aware-serialization) - Unity types just work | 10 minutes |
101-
| 🛠️ Manual sprite workflows | [**Editor Tools**](#editor-tools) - 20+ automation tools | 3 minutes |
93+
| Your Problem | Your Solution | Time to Value |
94+
| ------------------------------------ | ---------------------------------------------------------------------------------------------------- | ------------- |
95+
| 🎨 Writing custom editors | [**Inspector Tooling**](#1--professional-inspector-tooling) - Inspector tooling for common use cases | ~2 minutes |
96+
| 🐌 Writing `GetComponent` everywhere | [**Relational Components**](#2--auto-wire-components) - Auto-wire with attributes | ~2 minutes |
97+
| 🎮 Need buffs/debuffs system | [**Effects System**](#3--data-driven-effects) - Designer-friendly ScriptableObjects | ~5 minutes |
98+
| 🔍 Slow spatial searches | [**Spatial Trees**](#spatial-trees) - O(log n) queries | ~5 minutes |
99+
| 🎲 Random is too slow/limited | [**PRNG.Instance**](#random-number-generators) - 10-15x faster, extensive API | ~1 minute |
100+
| 💾 Need save/load system | [**Serialization**](#4--unity-aware-serialization) - Unity types just work | ~10 minutes |
101+
| 🛠️ Manual sprite workflows | [**Editor Tools**](#editor-tools) - 20+ automation tools | ~3 minutes |
102102

103-
**Not sure where to start?**[Getting Started Guide](./docs/overview/getting-started.md) walks through the top 3 features in 5 minutes.
103+
**Not sure where to start?**[Getting Started Guide](./docs/overview/getting-started.md) walks through the top 3 features in ~5 minutes.
104104

105105
---
106106

107107
## ⚡ Top Time-Savers
108108

109-
These features eliminate entire categories of repetitive work. Pick one that solves your immediate pain:
109+
These features address common categories of repetitive work. Pick one that solves your immediate pain:
110110

111111
### 1. 🎨 Professional Inspector Tooling
112112

113-
#### ⏱️ 5-10 min/script × 200 scripts = 20+ hours saved on custom editors
114-
115-
Stop writing custom PropertyDrawers and EditorGUI code. Get Odin Inspector-level features for free:
113+
Reduce custom PropertyDrawer and EditorGUI code with declarative attributes:
116114

117115
```csharp
118116
// ❌ OLD WAY: 100+ lines of custom editor code
@@ -164,9 +162,7 @@ public class CharacterStats : MonoBehaviour
164162

165163
### 2. 🔌 Auto-Wire Components
166164

167-
#### ⏱️ 10-20 min/script × 100 scripts = 20+ hours saved
168-
169-
Stop writing GetComponent boilerplate forever. Replace 20+ lines with 3 attributes:
165+
Reduce GetComponent boilerplate with declarative attributes. Replace 20+ lines with 3 attributes:
170166

171167
```csharp
172168
// ❌ OLD WAY: 20+ lines per script
@@ -196,9 +192,7 @@ void Awake() => this.AssignRelationalComponents();
196192

197193
### 3. 🎮 Data-Driven Effects
198194

199-
#### ⏱️ 2-4 hours/effect × 50 effects = 150+ hours saved
200-
201-
Designers create buffs/debuffs as ScriptableObjects. Zero programmer time after 20-minute setup:
195+
Designers create buffs/debuffs as ScriptableObjects. Minimal programmer involvement after initial setup:
202196

203197
```csharp
204198
// Create once (ScriptableObject in editor):
@@ -225,7 +219,7 @@ player.RemoveEffects(player.GetHandlesWithTag("Haste")); // Batch removal
225219

226220
### 4. 💾 Unity-Aware Serialization
227221

228-
#### ⏱️ 40+ hours on initial implementation + prevents player data loss
222+
#### Handles Unity type serialization and helps prevent player data loss
229223

230224
JSON/Protobuf that understands `Vector3`, `GameObject`, `Color` - no custom converters needed:
231225

@@ -255,9 +249,7 @@ byte[] data = Serializer.JsonSerialize(saveData);
255249

256250
### 5. 🎱 Professional Pooling
257251

258-
#### ⏱️ Eliminates GC spikes = 5-10 FPS in complex scenes
259-
260-
Zero-allocation queries with automatic cleanup. Thread-safe pooling in one line:
252+
Reduces GC pressure in allocation-heavy scenarios. Zero-allocation queries with automatic cleanup. Thread-safe pooling in one line:
261253

262254
```csharp
263255
// Get pooled buffer - automatically returned on scope exit
@@ -288,14 +280,12 @@ void ProcessEnemies(QuadTree2D<Enemy> enemyTree) {
288280

289281
### 6. 🛠️ Editor Tools Suite
290282

291-
#### ⏱️ 1-2 hours/operation × weekly use = 100+ hours/year
292-
293283
20+ tools that automate sprite cropping, animation creation, atlas generation, prefab validation:
294284

295285
**Common workflows:**
296286

297287
- **Sprite Cropper**: Add or remove transparent pixels from 500 sprites → 1 click (was: 30 minutes in Photoshop)
298-
- **Animation Creator**: Bulk-create clips from naming patterns (`walk_0001.png`) → 1 minute (was: 20 minutes)
288+
- **Animation Creator**: Bulk-create clips from naming patterns (`walk_0001.png`) → ~1 minute (was: ~20 minutes)
299289
- **Prefab Checker**: Validate 200 prefabs for missing references → 1 click (was: manual QA)
300290
- **Atlas Generator**: Create sprite atlases from regex/labels → automated (was: manual setup)
301291

@@ -305,9 +295,9 @@ void ProcessEnemies(QuadTree2D<Enemy> enemyTree) {
305295

306296
## 🎁 Batteries-Included Extensions
307297

308-
**Stop Googling "Unity how to..." for the 100th time.**
298+
**Common operations available as extension methods.**
309299

310-
Unity Helpers includes 200+ extension methods that handle the tedious stuff you're tired of writing:
300+
Unity Helpers includes 200+ extension methods that handle common repetitive patterns:
311301

312302
### Unity Type Extensions
313303

@@ -372,26 +362,26 @@ string apiKey = "user_name".ToPascalCase(); // "UserName"
372362

373363
These powerful utilities solve specific problems that waste hours if you implement them yourself:
374364

375-
| Feature | What It Does | Time Saved |
376-
| ------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------ |
377-
| **[Predictive Targeting](./docs/features/utilities/helper-utilities.md#predictive-aiming)** | Perfect ballistics for turrets/missiles in one call | 2-3 hours per shooting system |
378-
| **[Coroutine Jitter](./docs/features/utilities/math-and-extensions.md#unity-extensions)** | Prevents 100 enemies polling on same frame | Eliminates frame spikes |
379-
| **[IL-Emitted Reflection](./docs/features/utilities/reflection-helpers.md)** | 100x faster than System.Reflection, IL2CPP safe | Critical for serialization/modding |
380-
| **[SmartDestroy()](./docs/features/utilities/helper-utilities.md#smart-destruction)** | Editor/runtime safe destruction (no scene corruption) | Prevents countless debugging hours |
381-
| **[Convex/Concave Hulls](./docs/features/spatial/hulls.md)** | Generate territory borders from point clouds | 4-6 hours per hull algorithm |
382-
| **[Logging Extensions](./docs/features/logging/logging-extensions.md)** | Rich tags, thread-aware logs, per-object toggles | Keeps consoles readable + actionable |
365+
| Feature | What It Does | Benefit |
366+
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------- |
367+
| **[Predictive Targeting](./docs/features/utilities/helper-utilities.md#predictive-aiming)** | Perfect ballistics for turrets/missiles in one call | Simplifies implementation |
368+
| **[Coroutine Jitter](./docs/features/utilities/math-and-extensions.md#unity-extensions)** | Prevents 100 enemies polling on same frame | Reduces frame spikes |
369+
| **[IL-Emitted Reflection](./docs/features/utilities/reflection-helpers.md)** | 10-100x faster than System.Reflection (varies by operation), IL2CPP safe | Improves serialization performance |
370+
| **[SmartDestroy()](./docs/features/utilities/helper-utilities.md#smart-destruction)** | Editor/runtime safe destruction (no scene corruption) | Works across editor/runtime |
371+
| **[Convex/Concave Hulls](./docs/features/spatial/hulls.md)** | Generate territory borders from point clouds | Avoids manual hull calculation |
372+
| **[Logging Extensions](./docs/features/logging/logging-extensions.md)** | Rich tags, thread-aware logs, per-object toggles | Improves debugging |
383373

384374
---
385375

386376
## Why Teams Choose Unity Helpers
387377

388-
**The Reality:** You're spending 30-40% of your time writing the same GetComponent boilerplate, spatial query loops, and save/load plumbing over and over. Unity Helpers gives you that time back.
378+
Common Unity development patterns like GetComponent calls, spatial queries, and serialization often involve repetitive code. Unity Helpers provides utilities for these patterns.
389379

390380
**Built for Real Projects:**
391381

392382
-**Production-tested** in shipped commercial games
393383
-**8,000+ automated tests** catch edge cases before you hit them
394-
-**Zero dependencies** - drop it in any project
384+
-**Zero external dependencies** — protobuf-net is bundled for binary serialization
395385
-**IL2CPP/WebGL ready** with optimized SINGLE_THREADED paths
396386
-**MIT Licensed** - use freely in commercial projects
397387

@@ -1257,14 +1247,14 @@ Unity Helpers is built with performance as a top priority:
12571247

12581248
**Random Number Generation:**
12591249

1260-
- 10-15x faster than Unity.Random (655-885M ops/sec vs 65-85M ops/sec)
1250+
- Benchmarks show 10-15x faster generation than Unity.Random. Results vary by generator and operation; see performance documentation for details.
12611251
- Zero GC pressure with thread-local instances
12621252
- [📊 Full Random Performance Benchmarks](./docs/performance/random-performance.md)
12631253

12641254
**Spatial Queries:**
12651255

12661256
- O(log n) tree queries vs O(n) linear search
1267-
- 100-1000x faster for large datasets
1257+
- Significant speedup for large datasets due to O(log n) complexity
12681258
- QuadTree2D: 10,000 objects = ~13 checks vs 10,000 checks
12691259
- [📊 2D Performance Benchmarks](./docs/performance/spatial-tree-2d-performance.md)
12701260
- [📊 3D Performance Benchmarks](./docs/performance/spatial-tree-3d-performance.md)
@@ -1273,11 +1263,11 @@ Unity Helpers is built with performance as a top priority:
12731263

12741264
- Zero-allocation buffering pattern eliminates GC spikes
12751265
- Professional-grade pooling for List, HashSet, Stack, Queue, Arrays
1276-
- 5-10 FPS improvement in complex scenes from stable GC
1266+
- Reduces GC pressure in allocation-heavy scenarios
12771267

12781268
**Reflection:**
12791269

1280-
- Cached delegates are 10-100x faster than raw `System.Reflection` (boxed scenarios improve the most)
1270+
- Cached delegates are 10-100x faster than raw `System.Reflection` (method invocations ~12x; boxed scenarios up to 100x)
12811271
- Safe for IL2CPP and AOT platforms; capability overrides (`ReflectionHelpers.OverrideReflectionCapabilities`) let tests force expression/IL fallbacks
12821272
- Run the benchmarks via **ReflectionPerformanceTests.Benchmark** (EditMode Test Runner) and commit the updated markdown section
12831273
- [📘 Reflection Helpers Guide](./docs/features/utilities/reflection-helpers.md) and [📊 Benchmarks](./docs/performance/reflection-performance.md)

cspell.json

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -590,6 +590,8 @@
590590
"bsp",
591591
"PRNG",
592592
"prng",
593+
"PRNGs",
594+
"prngs",
593595
"PVRTC",
594596
"RNG",
595597
"rng",

0 commit comments

Comments
 (0)