f8-features-obfuz-workflow

name	f8-features-obfuz-workflow
description	Use when implementing or troubleshooting Obfuz feature workflows — code obfuscation and protection in F8Framework.

Obfuz Feature Workflow

⚠️ IMPORTANT: Before using this feature, you MUST formally initialize F8Framework in the launch sequence. Ensure ModuleCenter.Initialize(this); has run first.

Use this skill when

• The task is about code obfuscation or protection using Obfuz.
• The user asks about protecting compiled assemblies from reverse engineering.
• The task includes Obfuz + HybridCLR integration or hot-update DLL obfuscation.

Path resolution

1. Prefer project source at Assets/F8Framework.
2. For usage docs, read both:
   • Assets/F8Framework/Tests/Obfuz/README.md
   • Assets/F8Framework/Tests/Obfuz/README_EN.md
3. If docs need updates, keep the Chinese and English README files aligned.

Sources of truth

• Test docs: Assets/F8Framework/Tests/Obfuz
• Launcher/build integration points:
  • Assets/F8Framework/Editor/F8Helper/F8Helper.cs
  • hot-update entry LoadDll.cs in the target project
• Obfuz package / extension behavior as referenced by the test docs:
  • Assets/Packages/com.code-philosophy.obfuz4hybridclr/README.md

Key settings and integration points

Item	Guidance
Obfuz import	Import Obfuz first from https://github.com/focus-creative-games/obfuz.git.
AssembliesToObfuscate	Add Assembly-CSharp, F8Framework.Core, F8Framework.Launcher, F8Framework.F8ExcelDataClass.
NonObfuscatedButReferencingObfuscatedAssemblies	Add F8Framework.Core.Editor, F8Framework.Tests, F8Framework.ExcelData.Runtime. Keep F8Framework.ExcelData.Runtime out of AssembliesToObfuscate.
HybridCLR prebuild	Replace the HybridCLR-only prebuild command with Obfuz4HybridCLR.PrebuildCommandExt.GenerateAll();.
Encryption init	Move Obfuz EncryptionService initialization code to the hot-update entry LoadDll.cs.
API compatibility	Set Api Compatibility Level to .NET Framework.

Workflow

1. Import Obfuz into Unity first.
2. Generate the Obfuz key by following the official quick-start guide, and mount the generated initialization code.
3. Open the ObfuzSettings window and populate the two assembly lists exactly as documented in Tests/Obfuz/README.md and README_EN.md.
4. If the project uses HybridCLR, update F8Helper.cs:
   • in GenerateCopyHotUpdateDll, replace the prebuild command with Obfuz4HybridCLR.PrebuildCommandExt.GenerateAll();
   • uncomment the branch that redirects DLL output to GetObfuscatedHotUpdateAssemblyOutputPath(...)
5. Move the Obfuz EncryptionService initialization code into the hot-update entry LoadDll.cs.
6. Set Api Compatibility Level to .NET Framework.
7. Run F8 / build the project and verify the obfuscated output still works.

Common error handling

Error	Cause	Solution
API compatibility errors	Compatibility level is too low	Switch Api Compatibility Level to .NET Framework
F8Framework.ExcelData.Runtime references obfuscated F8Framework.Core	Excel Runtime is non-obfuscated but missing from Obfuz's referencing-assembly list	Add F8Framework.ExcelData.Runtime to NonObfuscatedButReferencingObfuscatedAssemblies; do not add it to both assembly lists
F8Framework code breaks after obfuscation	Too many framework assemblies are obfuscated	Try setting all F8Framework assemblies to non-obfuscated first, then narrow scope
Real-time Excel loading fails	Obfuz affects runtime config loading path	Use FF8.Config.RuntimeLoadAll() for runtime Excel reload
GeneratedEncryptionVirtualMachine.cs init error	Generated file path is wrong	Fix the path in the ObfuzSettings window
HybridCLR hot-update DLL not found	F8Helper prebuild/output path not switched to Obfuz	Use Obfuz4HybridCLR.PrebuildCommandExt.GenerateAll() and the obfuscated output-path branch

Cross-module dependencies

• HybridCLR: Required when hot-update DLLs also need Obfuz processing.
• Build/F8Helper: Obfuscation is wired into the prebuild/build pipeline.
• ExcelTool / Config: Real-time Excel reload may need FF8.Config.RuntimeLoadAll() after integration.

Output checklist

• Obfuz import path confirmed.
• Obfuscation target assemblies defined.
• Non-obfuscated referencing assemblies defined.
• HybridCLR integration points updated when applicable.
• Encryption initialization location confirmed.
• Build test passed with obfuscation.
• Validation status and remaining risks.