▚s&box/field-guide
▚ field-guide / building-ui
uirazorsilent-failure
the symptom, in your words

"The Razor @namespace trap"

✓ verified on engine 26.07lane: Building UIposted
▸ SYMPTOM
  • C#: type Hud not found / can't reference your PanelComponent.
  • Razor resolves the wrong type (Sandbox built-in) and you get baffling "no such member" errors.
  • Plain .cs classes without a namespace work; .razor siblings don't show up beside them.
▸ CAUSE

.razor files do NOT land in the global namespace the way namespace-free plain .cs classes do. They get a RootNamespace / folder-derived namespace.

Related: never name classes after Sandbox built-ins (PlayerController, etc.). A global-namespace name may compile, but razor resolves Sandbox.* first.

Scene/bootstrap JSON that references types by short name also expects some bootstrap classes to stay namespace-free — keep those specific entry types namespace-free if your scene already binds that way. (needs verification) against your .scene type strings.

▸ FIX

In every .razor:

snippet
@namespace YourGame

In Assembly.cs (or equivalent):

snippet
global using YourGame;

Then C# and other razor files can see Hud, InventoryPanel, etc.

Rename player/camera/inventory-ish classes away from Sandbox API names before you fight phantom member errors.

▸ WHY IT WORKS

The Razor generator emits classes into a project-derived namespace unless you override it. global using puts that namespace in scope for the rest of the game assembly so panel types behave like your other gameplay types. Explicit @namespace also stops accidental collisions with Sandbox.UI names.

✓
Verified on engine 26.07 — seen in a real project.
s&box moves fast; an undated fix is a liability. Spot a stale detail?
related gotchas
My s&box UI won't update / is frozen
BuildHash() is the only re-render trigger — hash everything the markup reads, including collection contents and flags.
Building an s&box HUD
One ScreenPanel host, static UIState for modals, self-closing panels, toast stack — BuildHash every flag the markup reads.
PanelComponent uses OnTreeBuilt, not OnAfterTreeRender
OnAfterTreeRender(bool) is a Panel hook — on a PanelComponent it fails with CS0115; use parameterless OnTreeBuilt() or OnTreeFirstBuilt().
Headless dotnet build misses Razor compile errors
dotnet build reports 0 errors on .razor files the in-editor compiler rejects — the headless build doesn't surface the Razor errors the live editor's Roslyn compiler flags.