Skip to content

t1k:unity:base:gups-il-obfuscation

FieldValue
Modulebase
Version5.116.6
Effortlow
Tools—

Keywords: Addressables obfuscation, anti-tamper, Code Integrity Check, DoNotObfuscateClass, DoNotRename, GUPS, GUPS.Obfuscator, IL2CPP obfuscation, mapping file, ObfuscateAnyway, obfuscated build, obfuscation, obfuscator, stack trace deobfuscation, TheOneObfuscator

/t1k:unity:base:gups-il-obfuscation

Configure and verify IL obfuscation. The tool is GUPS Obfuscator 2026.1.4 (Pro), vendored as the TheOneObfuscator git submodule. It hooks Unity’s build pipeline and rewrites the managed assemblies during a normal build — there is no separate “obfuscate” build step to add.

Scope: indexes this repo’s wiring plus the vendored tool’s own shipped code. Anything not stated here is unverified — grep, and state the scope before concluding absence (negative-result-scope.md). The submodule is read-only from this repo (reproducible-on-every-machine-unity.md).

⚠ Read this first — the submodule MUST live at Assets/GUPS, never anywhere else

Section titled “⚠ Read this first — the submodule MUST live at Assets/GUPS, never anywhere else”

The shipped GUPS.Obfuscator.Editor hardcodes its directory root to Application.dataPath + "/GUPS" (PathHelper.Get_GUPS_Directory()) and loads every Settings-page icon, On/Off button and foldout texture from Assets/GUPS/Obfuscator/Editor/Gui/Resources/... (verified: string literals in the DLL). The DLLs do not follow the folder they sit in. Clone the submodule anywhere but Assets/GUPS and:

  • Project Settings > GuardingPearSoftware > Obfuscator renders greyed-out with no On/Off toggle, and the product cards on the GuardingPearSoftware page are blank (textures resolve to null);
  • Unity auto-creates a fresh, empty Assets/GUPS/Obfuscator/Settings/Obfuscator_Settings.json (Global_Enable_Obfuscation falls back to false), PreBuild logs [GUPS.OBF] Obfuscation is deactivated by settings! and returns. A build ships unobfuscated and says nothing louder than a warning.

With the submodule at Assets/GUPS, the paths resolve inside it:

Assets/GUPS/Obfuscator/Settings/Obfuscator_Settings.json <- the LIVE settings file (tracked in the submodule)
Assets/GUPS/Obfuscator/Log/<BuildTarget>.txt <- the build log
Assets/GUPS/Obfuscator/Temp/ <- mapping fallback + keys

Because those are inside the submodule working tree, saving settings or running a build dirties the submodule. Settings changes are submodule commits: PR them in The1Studio/TheOneObfuscator, then bump the pointer (see “Submodule hygiene”).

IntentRead
Turn obfuscation on, or change what gets renamedreferences/settings-and-exclusions.md
Stop a class/method being renamedreferences/settings-and-exclusions.md § Attributes
Find or keep the mapping filereferences/settings-and-exclusions.md § Mapping
A build broke after obfuscationreferences/verification-and-deobfuscation.md
Deobfuscate a crash / stack tracereferences/verification-and-deobfuscation.md § Stack traces
Add the tool to another Unity project§ “Two consumption modes” below
The folder exists but assemblies are missing§ “Uninitialised submodule” below

Verified from the shipped settings schema and the decompiled GUPS.Obfuscator.Editor:

SurfaceVendor defaultNotes
Methods · parameters · events · stringsonStrings skipped in [BurstCompile] code (Burst BC1347)
Namespaces · classes · fields · propertiesoffSub-keys already True; flipping the master enables all visibilities
Per-assembly obfuscationonAssembly-CSharp, -firstpass, Assets/** and Packages/** asmdefs
Anti-tamper (Code Integrity Check) · Sign Assemblyoff / emptyMono-only
Addressables bundle + catalogoncatalog.json only; binary catalog unsupported

Anything in the GUPS namespace is always skipped. UnityEngine.Purchasing, System.Text.Json, Newtonsoft.Json and the other SDK compatibility components are skipped by default (see reference).

Two consumption modes — never both in one project

Section titled “Two consumption modes — never both in one project”

(1) Development — as a submodule at Assets/GUPS (this repo’s current state).

Terminal window
git submodule add git@github.com:The1Studio/TheOneObfuscator.git UnityTheOneFeatureProject/Assets/GUPS

The path must be Assets/GUPS (see “Read this first”); the submodule name is irrelevant, only the path matters. The tool is then ordinary Editor code in an Assets/ folder. To change the tool itself: edit and PR in The1Studio/TheOneObfuscator, then bump the pointer here. Never patch the submodule in place (reproducible-on-every-machine-unity.md).

(2) Usage in other projects — as a UPM package under Packages/: does not work yet. The repo has no root package.json, and the GUI textures load from Assets/GUPS/. The two gaps, the sketch manifest and the command: references/consumption-modes.md.

Never both in one project. Both copies define the same assembly names (GUPS.Obfuscator, GUPS.Editor) and the same .meta GUIDs → duplicate-assembly and duplicate-GUID compile errors (exact GUIDs in references/settings-and-exclusions.md § Two copies).

  • Fresh clone or CI: git submodule update --init --recursive. Nothing else populates the folders.
  • Wrong-path symptom: submodule cloned to any path other than Assets/GUPS (e.g. the old Assets/TheOneObfuscator) → greyed Obfuscator settings page, no toggle, blank cards. Fix: move it to Assets/GUPS (git mv; keep or delete the stray auto-generated Assets/GUPS/ first).
  • Uninitialised symptom: Assets/GUPS exists but is empty except a .git entry → the obfuscator assemblies vanish, references to GUPS.Obfuscator.Attribute fail with CS0246, and builds run with no obfuscation. Fix = git submodule update --init, then t1k unity recompile.
  • History: a tracked Assets/GUPS tree existed on an unmerged branch and is absent from HEAD; the exact provenance is verify, not asserted here (references/settings-and-exclusions.md § Two copies).
PiecePath under UnityTheOneFeatureProject/
Submodule (edit only via PR in its repo)Assets/GUPS/ → git@github.com:The1Studio/TheOneObfuscator.git (pinned pointer: git ls-tree HEAD Assets/GUPS)
Vendor docsAssets/GUPS/Obfuscator/Read_Me.md, Version_History.md
Build hook (all five callbacks)Assets/GUPS/Obfuscator/Editor/BuildPostProcessor.cs
Runtime attributesAssets/GUPS/Obfuscator/Plugins/Source/Attribute/
AssembliesGUPS.Obfuscator.asmdef (Obfuscator/Plugins/), GUPS.Editor.asmdef (Obfuscator/Editor/Source/, Editor-only)
Live settingsAssets/GUPS/Obfuscator/Settings/Obfuscator_Settings.json (inside the submodule)
LogAssets/GUPS/Obfuscator/Log/<BuildTarget>.txt
Mapping (vendor default)Build/Info/mapping-ops.txt — covered by /[Bb]uild/ in .gitignore
Submodule wiring.gitmodules

The package id com.guardingpearsoftware.obfuscator.pro appears in Packages/manifest.json only inside scopedRegistries[].scopes and in ProjectSettings/PackageManagerSettings.asset — not in dependencies and not in packages-lock.json. The tool is vendored, not resolved from the registry.

  1. Assembly scope. Every asmdef is in scope by default. Exclude third-party code on the attribute/namespace side rather than disabling the whole assembly pass (references/settings-and-exclusions.md).
  2. Settings. Open the Project/GuardingPearSoftware/Obfuscator provider, or edit Assets/GUPS/Obfuscator/Settings/Obfuscator_Settings.json. Set Global_Enable_Obfuscation: true — the only switch that matters; every phase re-reads it.
  3. Excludes. Mark reflection-, serialization- and SDK-facing types with the GUPS attributes. Prefer an attribute over a global exclusion.
  4. Build normally. No special step. BuildPostProcessor runs pre-build, post-assembly, linker, post-assets and post-build, each with callbackOrder => int.MaxValue (last). It bails if scenes are unsaved, or if BuildPipeline.isBuildingPlayer is false.
  5. Keep the mapping. It is the only way back from a crash report. Confirm it landed in Build/Info/mapping-ops.txt (or the custom path) and archive it with the build.
  6. Verify per references/verification-and-deobfuscation.md before shipping.

CI/batch: the hook fires inside BuildPipeline.BuildPlayer, so any batch build obfuscates with no extra flag. This repo’s CI shows no explicit obfuscation call — Jenkinsfile/ contains one-line stubs (android(this), ios(this), webgl(this)) and JenkinsScripts/ has no BuildPlayer / executeMethod; zero obfusc/GUPS hits. Whether the real pipelines go through BuildPipeline is verify. THEONE_OBFUSCATE is defined for Android only (ProjectSettings.asset) and has zero C# consumers — its purpose is verify.

A green build proves nothing. Four checks, details in the reference:

  1. Log at Assets/GUPS/Obfuscator/Log/<BuildTarget>.txt exists and carries no Obfuscation is deactivated by settings! line (a temp-dir log is not a keeper).
  2. The mapping file exists and is non-empty.
  3. On a player build: login/IAP, save→load, an Addressables load, a JSON round-trip, and a forced crash whose stack trace you deobfuscate with that build’s mapping.
  4. IL2CPP (here: Android + Standalone, stripping 3) rules out Sign Assembly and Code Integrity Check — both documented Mono-only.

The engine-neutral form of this checklist (log proves the tool ran, mapping archived per build, smoke matrix, deobfuscate with that build’s mapping) is the verification checklist of the core skill t1k-android-aab-obfuscation.

  • One copy per project. Both Assets/GUPS and Packages/TheOneObfuscator in one project is a compile error, not a preference.

  • Path is Assets/GUPS, always. Never add the submodule at any other path.

  • Never patch the submodule from this repo; PR in The1Studio/TheOneObfuscator and bump the pointer.

  • Never add a class that is reflected over or serialized by name without excluding it — obfuscated names break Type.GetType, JsonUtility, Newtonsoft.Json, Firebase, IAP product mapping and Addressables entry names at runtime, not at compile time.

  • Never delete or lose the mapping file; without it a crash report is unreadable.

  • Never declare a build “obfuscated” from a green build alone — check the log and the mapping.

  • Never “Reimport All”, never kill or restart the Editor, run headless (unity-headless-by-default.md, unity-forbidden-operations.md).

  • Do not commit build output: Build/ is ignored. A run also writes Assets/GUPS/Obfuscator/Log and Temp inside the submodule — never commit those from this repo; reset them in the submodule.

  • Silent success. With the submodule missing, uninitialised or at the wrong path, every phase returns true early. Exit code, build result and “no errors” prove nothing about obfuscation.

  • Settings saved in the Editor dirty the submodule (they write Assets/GUPS/Obfuscator/Settings/); the effective config then differs per machine until that change is PR’d in the submodule repo.

  • Unsaved scenes silently skip the whole pre-build phase.

  • The default mapping path Build/Info/mapping-ops.txt is gitignored (/[Bb]uild/) — archive it out of band or point Save_Mapping_FilePath elsewhere.

  • Addressables: only catalog.json is supported, and renaming MonoBehaviours also requires the globalgamemanagers.assets mapping; missing it yields the vendor line No MonoBehaviour obfuscation mapping found. The globalgamemanagers.assets file will not be obfuscated.

  • Scenes must be in Build Settings or the obfuscator’s scene pass has nothing to work on.

  • Enable_Assembly_Suppress_ILDasm is vendor behaviour; its exact effect on a stripped IL2CPP build is verify.

  • Generated C# is proven by a compile, never by a text match. A rename-tool test that asserts toContain on emitted C# stays green while the output fails a real Unity compile: a string passed to System.Array.IndexOf (CS1503), or an editor-only UnityEditor.InitializeOnLoadMethodAttribute compiled into a runtime assembly (CS0234, breaks the player build). Compile the output through the headless batch gate (unity-headless-by-default.md) on both an Editor-only layout and a layout where a package-root runtime asmdef covers Editor/, and wrap editor-only generated code in #if UNITY_EDITOR. Evidence: The1Studio/theonekit-unity#1255.

references/settings-and-exclusions.md (settings keys, attributes, SDK compatibility skips) · references/verification-and-deobfuscation.md (mapping, stack traces, runtime checks, IL2CPP/Mono) · reproducible-on-every-machine-unity.md · unity-headless-by-default.md · t1k-unity-tof-addressables (Addressables groups the catalog step touches) · t1k-unity-tof-notification-campaigns (sibling skill shape).

The rename tool lives in scripts/rename-company/. Config is layered: kit defaults in scripts/rename-company/rename-company.defaults.json, plus a per-game override at .claude/rename-company.json (passed with --config). Checklist, the Jenkins stage and the limits (what is and is not auto-detected, the report-only scanner, salt handling): references/rename-company.md. Tests: tests/rename-company/ (bun test tests/rename-company).

Running the rename tool test suite and reading the resolved config (config --field, config --allowlist) is mechanical: the output is a pass/fail count or a list, with no judgment. A cheap-tier agent runs it (routing SSOT: rules/orchestration-rules.md § “Task-Type → Agent Routing”):

StepAgent
bun test tests/rename-company and the config reportst1k-tester

Judgment stays with the caller: which strip paths and opt-ins a game gets, and whether a residue is acceptable.