f8-features-exceltool-workflow

ExcelTool Feature Workflow

⚠️ IMPORTANT: Before using this feature, you MUST formally initialize F8Framework in the launch sequence. Ensure ModuleCenter.Initialize(this); has run first, then create the required module, for example FF8.Config = ModuleCenter.CreateModule<F8DataManager>();.

Use this skill when

• The task is about config tables, Excel data reading, or data class generation.
• The user asks about F8 (generate) or F7 (runtime reload) shortcuts.
• The user needs to define new data types, containers, enums, or variants in Excel.
• Troubleshooting config loading failures or type mismatches.

Path resolution

1. Prefer project source at Assets/F8Framework.
2. If F8Framework is installed as a package, use Packages/F8Framework.
3. For usage docs, read: Assets/F8Framework/Tests/ExcelTool/README.md

Sources of truth

• Runtime module: Assets/F8Framework/Runtime/ExcelTool
• Editor module: Assets/F8Framework/Editor/ExcelTool
• Generated data classes: Assets/F8Framework/ConfigData
• Excel source: Assets/StreamingAssets/config/*.xlsx
• Test docs: Assets/F8Framework/Tests/ExcelTool

Key classes and interfaces

API quick reference

Loading config data

// Load single sheet by name
Sheet1 sheet1 = FF8.Config.Load<Sheet1>("Sheet1");
// Sync load all
FF8.Config.LoadAll();
// Async load all (coroutine)
yield return FF8.Config.LoadAllAsyncIEnumerator();
// Async load all (async/await — WebGL compatible)
await FF8.Config.LoadAllAsyncTask();
// Runtime Excel reload (development only)
FF8.Config.RuntimeLoadAll();

Querying data

// Get single row by ID
LogF8.Log(FF8.Config.GetSheet1ByID(2).name);
// Iterate all rows
foreach (var item in FF8.Config.GetSheet1())
{
    LogF8.Log(item.Key);
    LogF8.Log(item.Value.name);
}

Variant support (multi-language/multi-version configs)

// Set global variant name
FF8.Config.VariantName = "English";
// Set per-sheet variant name (higher priority)
Sheet1.VariantName = "English";

Excel type system

Basic types

char, bool, byte, short, int, long, float, double, decimal, str/string, obj/object, datetime, sbyte, ushort, uint, ulong Unity types: vec2/vector2, vec3/vector3, vec4/vector4, vec2int/vector2int, vec3int/vector3int, quat/quaternion, color, color32, matrix4x4 Standard JSON specification type: json

Container types

• Arrays: int[], string[][], obj[][][]
• Lists: list<obj>
• Dictionaries: dict<int,list<string>>
• ValueTuples: valuetuple<int,string> (up to 7 types)
• HashSets: hashset<int>

Special types

• Enums: enum<name,int,Flags>{Value1=1,Value2=2}
• Variants: variant<name,variantName> — switch configs by variant name

Row/column exclusion

• Skip entire row: leave id empty
• Skip entire column: leave type or name empty

Workflow

1. Create Excel files in Assets/StreamingAssets/config/ directory.
2. Set first column as int type id (unique primary key).
3. Row 1 = types, Row 2 = field names, Row 3+ = data.
4. Press F8 to generate binary files and C# data classes.
5. Generated files appear in Assets/F8Framework/ConfigData/ and Assets/AssetBundles/Config/BinConfigData/.
6. In code, call FF8.Config.LoadAll() before accessing data.
7. Press F7 for runtime Excel reload (development only).
8. For variants, add variant<fieldName,variantName> columns.

Common error handling

Cross-module dependencies

• AssetManager: Binary/JSON config files loaded via FF8.Asset.
• Localization: Can use variant type as lightweight localization alternative.

Output checklist

• Excel structure defined (types, names, data).
• F8/F7 generation verified.
• Data access code validated.
• Validation status and remaining risks.