t1k:unity:base:gups-il-obfuscation
| Field | Value |
|---|---|
| Module | base |
| Version | 5.116.6 |
| Effort | low |
| 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
How to invoke
Section titled “How to invoke”/t1k:unity:base:gups-il-obfuscationTheOne Obfuscation
Section titled “TheOne 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 > Obfuscatorrenders greyed-out with no On/Off toggle, and the product cards on theGuardingPearSoftwarepage are blank (textures resolve to null);- Unity auto-creates a fresh, empty
Assets/GUPS/Obfuscator/Settings/Obfuscator_Settings.json(Global_Enable_Obfuscationfalls back tofalse),PreBuildlogs[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 logAssets/GUPS/Obfuscator/Temp/ <- mapping fallback + keysBecause 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”).
Decision Tree
Section titled “Decision Tree”| Intent | Read |
|---|---|
| Turn obfuscation on, or change what gets renamed | references/settings-and-exclusions.md |
| Stop a class/method being renamed | references/settings-and-exclusions.md § Attributes |
| Find or keep the mapping file | references/settings-and-exclusions.md § Mapping |
| A build broke after obfuscation | references/verification-and-deobfuscation.md |
| Deobfuscate a crash / stack trace | references/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 |
What it obfuscates
Section titled “What it obfuscates”Verified from the shipped settings schema and the decompiled GUPS.Obfuscator.Editor:
| Surface | Vendor default | Notes |
|---|---|---|
| Methods · parameters · events · strings | on | Strings skipped in [BurstCompile] code (Burst BC1347) |
| Namespaces · classes · fields · properties | off | Sub-keys already True; flipping the master enables all visibilities |
| Per-assembly obfuscation | on | Assembly-CSharp, -firstpass, Assets/** and Packages/** asmdefs |
| Anti-tamper (Code Integrity Check) · Sign Assembly | off / empty | Mono-only |
| Addressables bundle + catalog | on | catalog.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).
git submodule add git@github.com:The1Studio/TheOneObfuscator.git UnityTheOneFeatureProject/Assets/GUPSThe 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).
Submodule hygiene
Section titled “Submodule hygiene”- 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 oldAssets/TheOneObfuscator) → greyed Obfuscator settings page, no toggle, blank cards. Fix: move it toAssets/GUPS(git mv; keep or delete the stray auto-generatedAssets/GUPS/first). - Uninitialised symptom:
Assets/GUPSexists but is empty except a.gitentry → the obfuscator assemblies vanish, references toGUPS.Obfuscator.Attributefail withCS0246, and builds run with no obfuscation. Fix =git submodule update --init, thent1k unity recompile. - History: a tracked
Assets/GUPStree existed on an unmerged branch and is absent fromHEAD; the exact provenance is verify, not asserted here (references/settings-and-exclusions.md§ Two copies).
Files (verified in this repo)
Section titled “Files (verified in this repo)”| Piece | Path 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 docs | Assets/GUPS/Obfuscator/Read_Me.md, Version_History.md |
| Build hook (all five callbacks) | Assets/GUPS/Obfuscator/Editor/BuildPostProcessor.cs |
| Runtime attributes | Assets/GUPS/Obfuscator/Plugins/Source/Attribute/ |
| Assemblies | GUPS.Obfuscator.asmdef (Obfuscator/Plugins/), GUPS.Editor.asmdef (Obfuscator/Editor/Source/, Editor-only) |
| Live settings | Assets/GUPS/Obfuscator/Settings/Obfuscator_Settings.json (inside the submodule) |
| Log | Assets/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.
Recipe
Section titled “Recipe”- 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). - Settings. Open the
Project/GuardingPearSoftware/Obfuscatorprovider, or editAssets/GUPS/Obfuscator/Settings/Obfuscator_Settings.json. SetGlobal_Enable_Obfuscation: true— the only switch that matters; every phase re-reads it. - Excludes. Mark reflection-, serialization- and SDK-facing types with the GUPS attributes. Prefer an attribute over a global exclusion.
- Build normally. No special step.
BuildPostProcessorruns pre-build, post-assembly, linker, post-assets and post-build, each withcallbackOrder => int.MaxValue(last). It bails if scenes are unsaved, or ifBuildPipeline.isBuildingPlayeris false. - 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. - Verify per
references/verification-and-deobfuscation.mdbefore 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.
Verifying an obfuscated build
Section titled “Verifying an obfuscated build”A green build proves nothing. Four checks, details in the reference:
- Log at
Assets/GUPS/Obfuscator/Log/<BuildTarget>.txtexists and carries noObfuscation is deactivated by settings!line (a temp-dir log is not a keeper). - The mapping file exists and is non-empty.
- 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.
- 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.
Hard rules
Section titled “Hard rules”-
One copy per project. Both
Assets/GUPSandPackages/TheOneObfuscatorin 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/TheOneObfuscatorand 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 writesAssets/GUPS/Obfuscator/LogandTempinside 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
trueearly. 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.txtis gitignored (/[Bb]uild/) — archive it out of band or pointSave_Mapping_FilePathelsewhere. -
Addressables: only
catalog.jsonis supported, and renaming MonoBehaviours also requires theglobalgamemanagers.assetsmapping; missing it yields the vendor lineNo 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_ILDasmis 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
toContainon emitted C# stays green while the output fails a real Unity compile: a string passed toSystem.Array.IndexOf(CS1503), or an editor-onlyUnityEditor.InitializeOnLoadMethodAttributecompiled 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 coversEditor/, and wrap editor-only generated code in#if UNITY_EDITOR. Evidence: The1Studio/theonekit-unity#1255.
Related
Section titled “Related”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).
Company-name rewrite (any game)
Section titled “Company-name rewrite (any game)”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).
Executed by
Section titled “Executed by”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”):
| Step | Agent |
|---|---|
bun test tests/rename-company and the config reports | t1k-tester |
Judgment stays with the caller: which strip paths and opt-ins a game gets, and whether a residue is acceptable.