Make the first message gameplay-driven

[Eli Pinkerton (wallstop)]

Summary

• replace the manually wired first-message examples with a trigger hazard that targets the exact GameObject it touches and a self-registering damage receiver
• document the minimum Unity collider/Rigidbody setup across the homepage, README, Quick Start, Getting Started, and Visual Guide
• remove maintainer-only storage, teardown, cache, workflow, and test-helper narratives from user-facing performance, diagnostics, and runtime guides
• strengthen the homepage contract with semantic targeting assertions and nine red/green manual-wiring cases
• let future .docs-tests/**-only pull requests skip licensed Unity/performance work while keeping static .NET docs tests blocking and fail-closed
• record the rejected lastTouchTicks dispatch experiment so later performance work does not repeat a stale-control result

Performance research

The runtime candidate was reverted. Fresh A/B/A Mono measurements were 24.786M / 24.844M / 25.208M emits/sec, leaving the candidate 0.6% below the control mean and below the 3% claim threshold. This PR changes no runtime code.

Validation

• Unity MCP comparison fixture: 6 passed, 0 failed
• documentation and homepage-contract tests: 592 passed
• source-generator tests: 246 passed
• script tests: 421 passed
• strict MkDocs build
• licensed-workflow classifier contract and fail-closed Unity PR policy validation
• repository-wide CSharpier, Prettier, markdownlint, cspell, offline link/anchor scan, tracked Markdown link-text check, npm run validate:all, and git diff --check
• documentation and CI adversarial review loops, each ending with zero findings
• branch merged current master before final CI; the base static, Unity, and performance workflows are green

Closes #404
Closes #411

Related: #414

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[github-actions]

Performance Numbers

Measured commit: ec08fe4
Trusted reporting code (PR base): d175562
Measured historical baseline: 4abe5a3
Workflow run: 31849629472 attempt 2

Benchmark methodology is unchanged; the historical Standalone comparison is diagnostic regression smoke.

Historical Standalone delta

Delta direction: + is better; - is worse.

Scenario	Baseline	Current	Delta
Empty Bus Dispatch	46.29 M emits/sec	45.22 M emits/sec	-2.31%
Untargeted Flood (One Handler)	29.47 M emits/sec	29.83 M emits/sec	+1.24%
Untargeted Flood (Two Handlers, One Priority)	32.09 M emits/sec	26.07 M emits/sec	-18.76%
Untargeted Flood (Three Handlers, One Priority)	25.65 M emits/sec	25.52 M emits/sec	-0.50%
Untargeted Flood (Four Handlers, One Priority)	29.29 M emits/sec	24.10 M emits/sec	-17.74%
Untargeted Flood (Four Handlers, Four Priorities)	31.83 M emits/sec	22.09 M emits/sec	-30.61%
Untargeted Flood (Sixteen Handlers, One Priority)	14.03 M emits/sec	14.87 M emits/sec	+5.93%
Untargeted Flood (One Inactive Handler)	31.66 M emits/sec	30.77 M emits/sec	-2.82%
Untargeted First Dispatch (Cold, Distinct Types)	0.199 ms	0.194 ms	+2.51%
Targeted Flood (No Matching Target)	14.16 M emits/sec	13.06 M emits/sec	-7.73%
Targeted Flood (One Listener)	10.88 M emits/sec	10.76 M emits/sec	-1.02%
Targeted Flood (Sixteen Listeners)	7.40 M emits/sec	7.73 M emits/sec	+4.49%
Targeted First Dispatch (Cold, Distinct Types)	0.192 ms	0.180 ms	+6.25%
Broadcast Flood (One Handler)	23.37 M emits/sec	26.09 M emits/sec	+11.67%
Broadcast First Dispatch (Cold, Distinct Types)	0.195 ms	0.201 ms	-3.08%
Interceptor Heavy (Four Interceptors)	22.92 M emits/sec	22.39 M emits/sec	-2.32%
Post-Processing Heavy (Four Post-Processors)	20.31 M emits/sec	18.84 M emits/sec	-7.23%
Message Bus Construction (1000)	20.020 ms	19.681 ms	+1.69%
Registration Token Construction (1000, Prebuilt Handler + Bus)	0.049 ms	0.048 ms	+2.04%
Registration Flood (1000 Types, Cold Bus)	559.377 ms	498.052 ms	+10.96%
Registration Flood (1000 Types, Warm JIT)	4.310 ms	3.404 ms	+21.02%
Untargeted Registration (Marginal, 1000 Same-Type)	0.402 ms	0.379 ms	+5.72%
Targeted Registration (Marginal, 1000 Same-Type)	0.439 ms	0.439 ms	0.00%
Broadcast Registration (Marginal, 1000 Same-Type)	0.443 ms	0.439 ms	+0.90%
Deregistration Flood (1000 Types, Cold)	1.711 ms	1.816 ms	-6.14%
Deregistration Flood (1000 Types, Warm JIT)	1.381 ms	1.026 ms	+25.71%
Deregistration Attribution (Direct Bus, 131072)	7.077 ms	6.960 ms	+1.65%
Deregistration Attribution (Direct Handler, 131072)	27.607 ms	27.645 ms	-0.14%
Deregistration Attribution (Token Remove, 131072)	33.207 ms	31.389 ms	+5.47%
Deregistration Attribution (Token Disable, 131072)	36.543 ms	36.460 ms	+0.23%
Global -> 1 subscriber	36.16 M emits/sec	38.34 M emits/sec	+6.02%
Global -> 16 subscribers	10.95 M emits/sec	19.26 M emits/sec	+75.97%
Keyed/targeted -> 1 of many	11.76 M emits/sec	13.03 M emits/sec	+10.81%
Priority-ordered dispatch	20.99 M emits/sec	22.80 M emits/sec	+8.61%
Filtered/intercepted dispatch	23.32 M emits/sec	22.89 M emits/sec	-1.83%
Post-processing dispatch	16.47 M emits/sec	27.79 M emits/sec	+68.73%
Subscribe/unsubscribe churn	0.97 M emits/sec	0.96 M emits/sec	-0.92%
Struct message (no boxing)	34.16 M emits/sec	27.48 M emits/sec	-19.53%

Current TargetMap evidence

These raw rows are current-run diagnostics. Use fresh bracketed controls before accepting a micro-optimization.

[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_16_Churn keyCount=16 operation=Churn totalOperations=2010000 operationsPerSecond=401998.135 wallClockMs=5000.023 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=16 targetMapCapacity=32 observedInvocations=2030000
[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_16_Hit keyCount=16 operation=Hit totalOperations=54480000 operationsPerSecond=10895179.375 wallClockMs=5000.377 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=16 targetMapCapacity=32 observedInvocations=54500000
[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_16_Miss keyCount=16 operation=Miss totalOperations=60490000 operationsPerSecond=12096861.927 wallClockMs=5000.470 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=16 targetMapCapacity=32 observedInvocations=0
[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_1_Churn keyCount=1 operation=Churn totalOperations=2040000 operationsPerSecond=406202.497 wallClockMs=5022.126 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=1 targetMapCapacity=4 observedInvocations=2060000
[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_1_Hit keyCount=1 operation=Hit totalOperations=55140000 operationsPerSecond=11026598.960 wallClockMs=5000.635 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=1 targetMapCapacity=4 observedInvocations=55160000
[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_1_Miss keyCount=1 operation=Miss totalOperations=58300000 operationsPerSecond=11658849.738 wallClockMs=5000.493 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=1 targetMapCapacity=4 observedInvocations=0
[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_256_Churn keyCount=256 operation=Churn totalOperations=1960000 operationsPerSecond=391882.200 wallClockMs=5001.503 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=256 targetMapCapacity=512 observedInvocations=1980000
[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_256_Hit keyCount=256 operation=Hit totalOperations=53160000 operationsPerSecond=10631258.789 wallClockMs=5000.349 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=256 targetMapCapacity=512 observedInvocations=53180000
[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_256_Miss keyCount=256 operation=Miss totalOperations=53430000 operationsPerSecond=10685862.580 wallClockMs=5000.064 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=256 targetMapCapacity=512 observedInvocations=0
[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_4096_Churn keyCount=4096 operation=Churn totalOperations=1440000 operationsPerSecond=287311.521 wallClockMs=5011.981 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=4096 targetMapCapacity=8192 observedInvocations=1460000
[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_4096_Hit keyCount=4096 operation=Hit totalOperations=41720000 operationsPerSecond=8341809.608 wallClockMs=5001.313 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=4096 targetMapCapacity=8192 observedInvocations=41740000
[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_4096_Miss keyCount=4096 operation=Miss totalOperations=57170000 operationsPerSecond=11432843.682 wallClockMs=5000.506 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=4096 targetMapCapacity=8192 observedInvocations=0
[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_4_Churn keyCount=4 operation=Churn totalOperations=2150000 operationsPerSecond=428968.066 wallClockMs=5012.028 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=4 targetMapCapacity=8 observedInvocations=2170000
[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_4_Hit keyCount=4 operation=Hit totalOperations=49620000 operationsPerSecond=9923565.745 wallClockMs=5000.219 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=4 targetMapCapacity=8 observedInvocations=49640000
[Standalone] DXM_TARGET_MAP_BENCHMARK scenario=TargetMap_4_Miss keyCount=4 operation=Miss totalOperations=55780000 operationsPerSecond=11153821.659 wallClockMs=5000.977 gcAllocations=-1 gcAllocatedBytes=-1 targetMapEntries=4 targetMapCapacity=8 observedInvocations=0
[Standalone] DXM_TARGET_MAP_CONSTRUCTION keyCount=1 wallClockMs=0.000104 operationsPerSecond=9661835.749 gcAllocations=-1 gcAllocatedBytes=-1 targetMapCapacity=4
[Standalone] DXM_TARGET_MAP_CONSTRUCTION keyCount=16 wallClockMs=0.000591 operationsPerSecond=1693121.693 gcAllocations=-1 gcAllocatedBytes=-1 targetMapCapacity=32
[Standalone] DXM_TARGET_MAP_CONSTRUCTION keyCount=256 wallClockMs=0.007900 operationsPerSecond=126582.278 gcAllocations=-1 gcAllocatedBytes=-1 targetMapCapacity=512
[Standalone] DXM_TARGET_MAP_CONSTRUCTION keyCount=4 wallClockMs=0.000210 operationsPerSecond=4761904.762 gcAllocations=-1 gcAllocatedBytes=-1 targetMapCapacity=8
[Standalone] DXM_TARGET_MAP_CONSTRUCTION keyCount=4096 wallClockMs=0.123200 operationsPerSecond=8116.883 gcAllocations=-1 gcAllocatedBytes=-1 targetMapCapacity=8192