# Codegen Pipeline

## Stability

Internal / Unsupported

## Scope

Defines the FlowCore code generation pipeline: terms, generator entry points, required tags, and the authoritative sequence to produce generated outputs and registries.

## Entry points

* Project Settings > Flow Core > Blackboard Entry: Custom Type Generator, Enum Resolver Generator
* Project Settings > Flow Core > Flow Graph Entry: Member Generator, Registry Generator
* Project Settings > Flow Core > Maintain: Generated Items

## Settings assets

\| Generator | Settings asset |

\| --- | --- |

\| Custom Type Generator | Assets/Resources/FlowCustomTypeGeneratorSettings.asset |

\| Enum Resolver Generator | Assets/Resources/FlowEnumResolverGeneratorSettings.asset |

\| Member Generator | Assets/Resources/FlowMemberGeneratorSettings.asset |

\| Registry Generator | Assets/Resources/FlowRegistryGeneratorSettings.asset |

## Terminology

* Codegen: The process that produces C# output files based on tags and generator settings.
* Generator: An editor tool that scans project types and writes generated files and registries.
* Registry: Generated lookup tables used by the editor runtime to find instruction, condition, enum, and drawer entries.
* Generated item: A file with `FlowGenerated` headers and a hash line, tracked by the Generated Items window.
* Graph asset wrapper: A `FlowGraphAssetBase` subclass that defines a custom `CreateRuntime` entry. It is a manual extension point, not produced by the built-in generators.

## Tags and attributes

\| Tag | Target | Used by | Purpose |

\| --- | --- | --- | --- |

\| FlowInstruction | class | Registry Generator | Marks instruction data types for registry. |

\| FlowCondition | class | Registry Generator | Marks condition data types for registry. |

\| FlowTypeGen | class/struct | Member Generator | Includes all members on a type for generation. |

\| FlowMemberGen | method/property/field | Member Generator | Includes a specific member for generation. |

\| FlowMemberGenExclude | class/struct/member | Member Generator | Excludes a type or member from generation. |

\| FlowCustomType | class/struct | Custom Type Generator | Generates blackboard bucket/serializer/nodes/drawer. | | FlowComponentReference | class (Component) | Custom Type Generator | Generates ComponentReference bucket/serializer/nodes/drawer. |

\| NoFlowAutoUI | class/struct | Custom Type Generator | Skips custom type generation for the tagged type. |

\| FloweCustomEnum | enum | Enum Resolver Generator | Includes an enum in the resolver whitelist. |

\| FlowValueAutoUI | class/struct | Editor UI | Enables automatic UI generation for a value container. |

\| FlowFieldAutoUI | field/property | Editor UI | Controls auto UI layout, visibility, and order. |

`FlowFieldAutoUI` key fields:

* Label: Overrides the display label.
* Show: Conditional expression, supports `$FieldName` references.
* Order: Lower values appear first; `-1` keeps declaration order.
* IsList: Enables reorder/remove controls for list items.
* ReadOnly: Disables editing.
* Foldout: Wraps the field in a foldout.
* Tooltip: Text shown under the label.

Example:

```csharp

[FlowCustomType(Category = "Gameplay", GenerateSerializer = true)]

public sealed class DamageProfile

{

    [FlowFieldAutoUI(Label = "Base Damage", Order = 0)]

    public int BaseDamage;

}

[FlowTypeGen]

public sealed class CombatApi

{

    [FlowMemberGen]

    public void ApplyDamage(int amount) {}

}

```

Note: the enum attribute name is `FloweCustomEnum` (spelled with an extra `e`).

## Authoritative generation flow

1. Add tags or enable the generator settings that include your target types.
2. Run the generators in sequence:
   * Custom Type Generator (for new blackboard types).
   * Enum Resolver Generator (for new enums used by blackboard or UI).
   * Member Generator (for methods/fields/properties you want as instructions/conditions).
   * Registry Generator (updates instruction/condition/enum/drawer registries).
3. Verify with Generated Items and editor search.

## Typical task sequences

* Add a custom blackboard type → Custom Type Generator → Registry Generator.
* Add a new enum for UI/blackboard → Enum Resolver Generator → Registry Generator.
* Expose a method as an instruction → Member Generator → Registry Generator.

## Shared scan and generated lookup rules

* Empty `Scan Directories` means no asset-path restriction. It does not imply a default root.
* Non-empty `Scan Directories` match against all declaration paths known for a type.
  * Top-level sibling types declared in the same `.cs` / `.g.cs` file inherit that file path for matching.
  * Partial types match when any declaration file path hits the configured directories.
* Generated lookup always treats the built-in output folder and the current generator output folder as valid generated sources.
* When `EnableProjectWideGeneratedCheck == true`, the generated lookup expands to other generated outputs in the project.
* Cross-assembly generated reuse is supported through generated-item metadata lookup, not by asmdef-name guessing.
* Candidate or pending entries are not treated as generated outputs. Only existing generated items satisfy missing-dependency checks.

## Validation checklist

* New types appear in search and node menus.
* Generated files are listed in Generated Items.
* Registries include your new types (no missing entries).

## Custom Type Generator outputs

* Output root (default): `Assets/FlowCore/CT`
* Generates runtime/editor folders with a `G` subfolder.
* Generates blackboard bucket, serializer, Flow Get/Set node data, and drawer if enabled by `FlowCustomType`.
* Uses the type-level settings as defaults when `FlowCustomType` does not override them.

## Enum Resolver Generator outputs

* Output root (default): `Assets/FlowCore/E`
* Generates enum buckets and serializers, plus a serializer registry group (`.rg.cs`).
* Enums are included by `FloweCustomEnum` or by whitelist settings in the settings asset.
* Only runtime-eligible enums are accepted. Editor-only, script-guarded editor-only, inaccessible, and non-runtime-assembly enums are excluded.

## Member Generator outputs

* Output root (default): `Assets/FlowCore/M`
* Generates instruction and condition data from fields/properties/methods.
* Uses FlowValue wrapper types to map parameters and return values.
* Respects `FlowTypeGen`, `FlowMemberGen`, and `FlowMemberGenExclude`.
* Component members generate two output contracts by design: a `Component` variant and a `GameObject` variant. This is generator behavior, not a per-API special case.
* In the `Component` variant, component-typed `Target`, parameters, setter `Value`, and getter/method write-back use the concrete component `FlowValueGet*` / `FlowValueSet*` wrappers instead of raw component fields.
* In the `GameObject` variant, component-typed slots become `GameObject + Scope + IncludeInactive + Index`, and the auto UI expands those fields explicitly.
* `GameObject` variant component outputs write back as `GameObject`, not as the original component type. Wrapper selection for parameters and return/write-back therefore changes with the generated variant.

## Migration note (Member Generator component variants)

* After regenerating with the new component-member rules, old raw component fields are replaced by either concrete `FlowValueGet*` / `FlowValueSet*` fields or by `GameObject + Scope + IncludeInactive + Index`.
* Typical affected examples include `Transform.parent`, `SetParent(Transform)`, and `SetParent(Transform, bool)`.
* After changing Member Generator rules, rerun Member Generator first and Registry Generator second so generated contracts and registries stay aligned.

## Known issue blacklist (Member Generator)

Some APIs are editor-only or removed in certain Unity versions and must never be generated into runtime assemblies. The generator keeps a small hardcoded blacklist in `FlowMemberGeneratorTypeUtility.IsKnownEditorOnlyMember` to prevent build errors.

Current blacklist:

* `UnityEngine.UI.Graphic.OnRebuildRequested`
* `UnityEngine.UI.Text.OnRebuildRequested`

## Registry Generator outputs

* Output root (default): `Assets/FlowCore/R/*`
* Generates registry groups (`.rg.cs`) for instructions, conditions, enums, and drawers.
* Required after adding new instruction/condition types or new custom drawers.
* The Enum registry flow aggregates already-generated enum resolver outputs. It does not scan raw enum declarations directly.

## Generated Items behavior

* Scans for `FlowGenerated` headers and hash markers.
* Regenerates selected files using their original generator metadata.
* Avoid manual edits to generated files; if a file is modified, regeneration may skip or overwrite depending on generator rules.

## Related

* [Built-in Catalog Overview](/flow-core-docs/documentation/reference/built-in-catalog-overview.md)
* [Codegen Generators](/flow-core-docs/documentation/api-extension-guide/codegen-generators.md)
* [Generated Items](/flow-core-docs/documentation/api-extension-guide/generated-items.md)
* [Auto UI Tags](/flow-core-docs/documentation/reference/auto-ui-tags.md)
* [FlowCore Settings](/flow-core-docs/documentation/reference/flow-core-settings.md)
* [Extension Points](/flow-core-docs/documentation/api-extension-guide/extension-points.md)
* [Graph Asset Wrapper](/flow-core-docs/documentation/api-extension-guide/graph-asset-wrapper.md)
* [Terminology](/flow-core-docs/documentation/reference/terminology.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://flow-core.gitbook.io/flow-core-docs/documentation/api-extension-guide/codegen-pipeline.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.