# illusionmods/koikatsumoddingtools architecture

> Architecture diagram of the GitHub repository illusionmods/koikatsumoddingtools, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/illusionmods/koikatsumoddingtools
- Repository: https://github.com/illusionmods/koikatsumoddingtools

## Overview

1. This repository is a Unity 5.6.2 editor project, not a game runtime by itself. Its purpose is to author Koikatsu mod assets and package them into the formats the game expects, mainly asset bundles and zipmods.

2. The architecture is split into three main boundaries: editor-time tooling under `Assets/Editor` and `Tools`, reusable mod/runtime components under `Assets/Scripts` and `Assets/AmplifyColor`, and content templates/examples under `Assets/Examples`. The examples show the expected file layout for real mods.

3. The build pipeline is centered on Unity asset import and export. Authors place textures, meshes, prefabs, manifests, and list files inside the `Assets/Mods` area or base an item on one of the example folders, then use the Unity AssetBundle Browser to build bundles and zipmods. The repo is structured so only content under `Mods` is treated as custom output, keeping examples separate.

4. `Assets/Editor` contains the repo’s main automation layer. It includes asset-bundle/zipmod utilities, manifest and list-file editors, texture postprocessing, FBX postprocessing, and custom inspectors for the mod component types. These scripts are responsible for turning raw Unity assets into Koikatsu-compatible package contents.

5. Import postprocessors are important to the workflow. The repository automatically adjusts imported meshes and textures: FBX assets can have excess bones removed and layers reassigned, while normal maps are converted to the red-transparent style expected by the target game ecosystem. This is one of the key “pre-export” data transformations in the project.

6. `Tools/SB3UGS` is an external packaging and replacement tool bundled with the repo. It is used after asset bundles are built to swap placeholder shaders back to game shaders and to support the zipmod workflow. That makes SB3UGS part of the release pipeline even though it is not Unity code.

7. The shader architecture is layered. `Assets/Shaders` contains the project’s custom and placeholder shaders, including many Koikatsu-specific shader variants, while `Assets/ShaderForge` and `Assets/AmplifyColor` provide editor tooling and reusable shader assets. The README makes clear that placeholder shaders are used in edit mode and later replaced for final builds.

8. The runtime-facing mod components live in `Assets/Scripts`. These include character-facing components for clothes, accessories, custom hair, foreground items, particles, and item logic, plus map/scene-related components such as gates, H-points, map visibility, lighting, reflection, and mini-map support. These scripts define the data that the editor tools serialize into mod content.

9. Character and facial systems are a distinct subsystem. Scripts such as `FaceBlendShape`, `EyeLookController`, `EyeLookCalc`, `FBSBlinkControl`, and the various `FBSCtrl*` classes handle eye movement, blinking, eyebrows, mouth, and other face-driven behaviors. These are separate from packaging and are focused on in-game appearance/animation behavior.

10. And scene support is another major subsystem. The `Assets/Scripts/Map` folder includes map metadata, lighting, background parameters, H-point data, gate grouping, reflection, sun shafts, and gizmo visualization. The `Assets/Examples/Map Example` folder mirrors this with prefabs, lighting data, reflection probes, and map CSVs, showing the intended content model.

11. VR support is included as a self-contained group under `Assets/Scripts/VR`. It contains `VRPoint` plus a set of VRTK interaction scripts, indicating the project can author content that participates in VR interaction and snap/attach behavior. This is a separate interaction boundary from standard character or studio items.

12. Preview and visualization assets under `Assets/Preview`, `Assets/Gizmos`, and `Assets/Common/H Point Selector` support authoring rather than runtime delivery. They provide preview scenes, camera/light prefabs, gizmo meshes, and H-point visual markers so creators can inspect content in-editor before packaging.

13. The examples are the clearest architectural documentation in the repo. There are separate example modules for body paint, accessories, accessory hair, clothes, head types, studio items, studio filters, maps, shader editing, and asset overrides. Each example contains its own manifest, list files, textures, meshes, materials, prefabs, and readme, showing the canonical artifact graph for each mod type.

14. A notable embedded dependency is `Assets/Editor/YamlDotNet`, which brings a full YAML serialization library into the editor tooling. This suggests some editor-side config or manifest-related workflows rely on structured serialization rather than hand-authored text alone.

Main entry points: [`Assets/Scripts/Map`](https://github.com/illusionmods/koikatsumoddingtools/tree/master/Assets/Scripts/Map) (Map System), [`Assets/Shaders`](https://github.com/illusionmods/koikatsumoddingtools/tree/master/Assets/Shaders) (Game Shaders), [`Assets/Editor`](https://github.com/illusionmods/koikatsumoddingtools/tree/master/Assets/Editor) (Import Pipeline), [`Assets/Scripts`](https://github.com/illusionmods/koikatsumoddingtools/tree/master/Assets/Scripts) (Character Mods)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_editor["Editor Tooling"]
  node_n_editor_import["Import Pipeline<br/>editor automation"]
  node_n_editor_manifest["Manifests<br/>metadata editors<br/>[ManifestCreate.cs]"]
  node_n_editor_post["Postprocessors<br/>asset transforms"]
  node_n_editor_bundle["Bundle Build<br/>packaging tools"]
  node_n_editor_yaml["YAML Core<br/>serialization lib"]
end

subgraph group_g_runtime["Runtime Components"]
  node_n_runtime_char["Character Mods<br/>runtime components"]
  node_n_runtime_face["Face System<br/>facial animation<br/>[FaceBlendShape.cs]"]
  node_n_runtime_map["Map System<br/>scene/map runtime"]
  node_n_runtime_vr["VR Hooks<br/>vr interaction"]
  node_n_runtime_preview["Render Helpers<br/>render support<br/>[PreviewShaders.cs]"]
end

subgraph group_g_examples["Examples"]
  node_n_examples_mods["Mod Examples<br/>content templates"]
  node_n_examples_map["Map Example<br/>example module"]
  node_n_examples_item["Item Example<br/>example module"]
  node_n_examples_shader["Shader Example<br/>example module"]
end

subgraph group_g_shaders["Shader Stack"]
  node_n_shaders_game{{"Game Shaders<br/>koikatsu shaders"}}
  node_n_shaders_forge["ShaderForge<br/>shader tooling"]
  node_n_shaders_amplify["AmplifyColor<br/>color grading"]
end

subgraph group_g_preview["Preview & Viz"]
  node_n_preview_assets["Preview Assets<br/>editor visuals"]
  node_n_gizmos["Gizmos<br/>visual markers"]
end

subgraph group_g_tools["External Tools"]
  node_n_sb3ugs["SB3UGS<br/>external packager"]
end

node_n_editor_import -->|"normalizes"| node_n_editor_post
node_n_editor_import -->|"writes"| node_n_editor_manifest
node_n_editor_import -->|"exports"| node_n_editor_bundle
node_n_editor_manifest -.->|"documents"| node_n_examples_mods
node_n_editor_yaml -->|"serializes"| node_n_editor_manifest
node_n_editor_post -->|"placeholder swap"| node_n_shaders_game
node_n_editor_bundle -->|"hands off"| node_n_sb3ugs
node_n_sb3ugs -->|"finalizes"| node_n_shaders_game
node_n_runtime_char -->|"uses"| node_n_runtime_face
node_n_runtime_char -->|"supports"| node_n_runtime_preview
node_n_runtime_map -->|"interacts with"| node_n_runtime_vr
node_n_runtime_map -->|"inspected by"| node_n_preview_assets
node_n_examples_map -.->|"models"| node_n_runtime_map
node_n_examples_item -.->|"models"| node_n_runtime_char
node_n_examples_shader -.->|"demonstrates"| node_n_shaders_forge
node_n_shaders_forge -->|"authors"| node_n_shaders_game
node_n_shaders_amplify -->|"provides"| node_n_preview_assets
node_n_gizmos -.->|"visualizes"| node_n_runtime_map
node_n_preview_assets -->|"configures"| node_n_shaders_game
node_n_examples_mods -.->|"reference build"| node_n_editor_bundle

click node_n_editor_import "https://github.com/illusionmods/koikatsumoddingtools/tree/master/Assets/Editor"
click node_n_editor_manifest "https://github.com/illusionmods/koikatsumoddingtools/blob/master/Assets/Editor/ManifestCreate.cs"
click node_n_editor_post "https://github.com/illusionmods/koikatsumoddingtools/blob/master/Assets/Editor/BlenderFBX_Postprocessor.cs"
click node_n_editor_bundle "https://github.com/illusionmods/koikatsumoddingtools/blob/master/Assets/Editor/Unity.AssetBundleBrowser"
click node_n_editor_yaml "https://github.com/illusionmods/koikatsumoddingtools/tree/master/Assets/Editor/YamlDotNet"
click node_n_runtime_char "https://github.com/illusionmods/koikatsumoddingtools/tree/master/Assets/Scripts"
click node_n_runtime_face "https://github.com/illusionmods/koikatsumoddingtools/blob/master/Assets/Scripts/FaceBlendShape.cs"
click node_n_runtime_map "https://github.com/illusionmods/koikatsumoddingtools/tree/master/Assets/Scripts/Map"
click node_n_runtime_vr "https://github.com/illusionmods/koikatsumoddingtools/tree/master/Assets/Scripts/VR"
click node_n_runtime_preview "https://github.com/illusionmods/koikatsumoddingtools/blob/master/Assets/Scripts/PreviewShaders.cs"
click node_n_examples_mods "https://github.com/illusionmods/koikatsumoddingtools/tree/master/Assets/Examples"
click node_n_examples_map "https://github.com/illusionmods/koikatsumoddingtools/tree/master/Assets/Examples/Map Example"
click node_n_examples_item "https://github.com/illusionmods/koikatsumoddingtools/tree/master/Assets/Examples/Studio Item Example"
click node_n_examples_shader "https://github.com/illusionmods/koikatsumoddingtools/tree/master/Assets/Examples/MaterialEditor Shader Example"
click node_n_shaders_game "https://github.com/illusionmods/koikatsumoddingtools/tree/master/Assets/Shaders"
click node_n_shaders_forge "https://github.com/illusionmods/koikatsumoddingtools/tree/master/Assets/ShaderForge"
click node_n_shaders_amplify "https://github.com/illusionmods/koikatsumoddingtools/tree/master/Assets/AmplifyColor"
click node_n_preview_assets "https://github.com/illusionmods/koikatsumoddingtools/tree/master/Assets/Preview"
click node_n_gizmos "https://github.com/illusionmods/koikatsumoddingtools/tree/master/Assets/Gizmos"
click node_n_sb3ugs "https://github.com/illusionmods/koikatsumoddingtools/tree/master/Tools/SB3UGS"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_editor_import,node_n_editor_manifest,node_n_editor_post,node_n_editor_bundle,node_n_editor_yaml toneBlue
class node_n_runtime_char,node_n_runtime_face,node_n_runtime_map,node_n_runtime_vr,node_n_runtime_preview toneAmber
class node_n_examples_mods,node_n_examples_map,node_n_examples_item,node_n_examples_shader toneMint
class node_n_shaders_game,node_n_shaders_forge,node_n_shaders_amplify toneRose
class node_n_preview_assets,node_n_gizmos toneIndigo
class node_n_sb3ugs toneTeal
```

## Components

### Editor Tooling

Unity editor automation for importing, annotating, and packaging mod content.

- [Import Pipeline](https://github.com/illusionmods/koikatsumoddingtools/tree/master/Assets/Editor): editor automation · Asset import hooks and postprocessors for Unity content preparation. · `Assets/Editor`
- [Manifests](https://github.com/illusionmods/koikatsumoddingtools/blob/master/Assets/Editor/ManifestCreate.cs): metadata editors · Manifest and list-file creation/editing for Koikatsu packaging. · `Assets/Editor/ManifestCreate.cs`
- [Postprocessors](https://github.com/illusionmods/koikatsumoddingtools/blob/master/Assets/Editor/BlenderFBX_Postprocessor.cs): asset transforms · FBX, layer, texture, and shader-placeholder preprocessing during import. · `Assets/Editor/BlenderFBX_Postprocessor.cs`
- [Bundle Build](https://github.com/illusionmods/koikatsumoddingtools/blob/master/Assets/Editor/Unity.AssetBundleBrowser): packaging tools · AssetBundle Browser integration plus zipmod build helpers. · `Assets/Editor/Unity.AssetBundleBrowser`
- [YAML Core](https://github.com/illusionmods/koikatsumoddingtools/tree/master/Assets/Editor/YamlDotNet): serialization lib · Embedded YamlDotNet dependency used by editor-side structured serialization. · `Assets/Editor/YamlDotNet`

### Runtime Components

Scripts and systems that define mod behavior inside Koikatsu.

- [Character Mods](https://github.com/illusionmods/koikatsumoddingtools/tree/master/Assets/Scripts): runtime components · Accessories, clothes, hair, foreground items, particles, and item logic. · `Assets/Scripts`
- [Face System](https://github.com/illusionmods/koikatsumoddingtools/blob/master/Assets/Scripts/FaceBlendShape.cs): facial animation · Eye, blink, eyebrow, mouth, and face blendshape control. · `Assets/Scripts/FaceBlendShape.cs`
- [Map System](https://github.com/illusionmods/koikatsumoddingtools/tree/master/Assets/Scripts/Map): scene/map runtime · Map metadata, gates, lighting, visibility, reflections, and mini-map support. · `Assets/Scripts/Map`
- [VR Hooks](https://github.com/illusionmods/koikatsumoddingtools/tree/master/Assets/Scripts/VR): vr interaction · VR point and VRTK-based grab, touch, use, and snap behavior. · `Assets/Scripts/VR`
- [Render Helpers](https://github.com/illusionmods/koikatsumoddingtools/blob/master/Assets/Scripts/PreviewShaders.cs): render support · Preview shader controls, render queue helpers, and collision helpers. · `Assets/Scripts/PreviewShaders.cs`

### Examples

Canonical content layouts that document how mod assets are assembled.

- [Mod Examples](https://github.com/illusionmods/koikatsumoddingtools/tree/master/Assets/Examples): content templates · Accessory, clothes, body paint, head type, studio, and override example layouts. · `Assets/Examples`
- [Map Example](https://github.com/illusionmods/koikatsumoddingtools/tree/HEAD/Assets/Examples/Map%20Example): example module · Example map content with prefabs, lighting data, probes, and CSV metadata. · `Assets/Examples/Map Example`
- [Item Example](https://github.com/illusionmods/koikatsumoddingtools/tree/HEAD/Assets/Examples/Studio%20Item%20Example): example module · Studio item example showing meshes, materials, prefabs, and list files. · `Assets/Examples/Studio Item Example`
- [Shader Example](https://github.com/illusionmods/koikatsumoddingtools/tree/HEAD/Assets/Examples/MaterialEditor%20Shader%20Example): example module · Material editor shader example with custom shader sources and presets. · `Assets/Examples/MaterialEditor Shader Example`

### Shader Stack

Custom shaders, shader editor assets, and placeholder/final shader flow.

- [Game Shaders](https://github.com/illusionmods/koikatsumoddingtools/tree/master/Assets/Shaders): koikatsu shaders · Custom and placeholder shaders for character, item, and studio rendering. · `Assets/Shaders`
- [ShaderForge](https://github.com/illusionmods/koikatsumoddingtools/tree/master/Assets/ShaderForge): shader tooling · ShaderForge editor assets, node library, and example shader content. · `Assets/ShaderForge`
- [AmplifyColor](https://github.com/illusionmods/koikatsumoddingtools/tree/master/Assets/AmplifyColor): color grading · Amplify Color runtime/editor package and LUT/volume shader assets. · `Assets/AmplifyColor`

### Preview & Viz

Editor-only scenes and assets for inspecting content before export.

- [Preview Assets](https://github.com/illusionmods/koikatsumoddingtools/tree/master/Assets/Preview): editor visuals · Preview scenes, cameras, lights, ramps, and shader settings for authoring. · `Assets/Preview`
- [Gizmos](https://github.com/illusionmods/koikatsumoddingtools/tree/master/Assets/Gizmos): visual markers · H-point gizmo meshes and selector assets used for editor visualization. · `Assets/Gizmos`

### External Tools

Bundled third-party tooling used in the release workflow.

- [SB3UGS](https://github.com/illusionmods/koikatsumoddingtools/tree/master/Tools/SB3UGS): external packager · Bundled external tool used after bundle build to swap shaders and support zipmods. · `Tools/SB3UGS`

## Connections

- Import Pipeline → Postprocessors: normalizes · Import pipeline applies postprocessing to incoming assets.
- Import Pipeline → Manifests: writes · Editor tooling generates manifest and list metadata.
- Import Pipeline → Bundle Build: exports · Prepared assets are handed to bundle/zipmod build tools.
- Manifests → Mod Examples: documents · Examples show the expected manifest and list structure.
- YAML Core → Manifests: serializes · YAML library supports structured editor-side config workflows.
- Postprocessors → Game Shaders: placeholder swap · Postprocessing prepares assets for placeholder shader workflow.
- Bundle Build → SB3UGS: hands off · Built bundles are processed by external packaging tooling.
- SB3UGS → Game Shaders: finalizes · SB3UGS supports replacing placeholders with game shaders for release.
- Character Mods → Face System: uses · Character systems include face and eye animation behavior.
- Character Mods → Render Helpers: supports · Runtime components use helper scripts for preview and rendering behavior.
- Map System → VR Hooks: interacts with · Map and scene content can include VR interaction points and snap behavior.
- Map System → Preview Assets: inspected by · Map authoring relies on preview lighting and scene assets.
- Map Example → Map System: models · Map example mirrors the runtime map component model.
- Item Example → Character Mods: models · Item/studio examples reflect the character and item component layout.
- Shader Example → ShaderForge: demonstrates · Shader example content is built on ShaderForge assets and presets.
- ShaderForge → Game Shaders: authors · ShaderForge is used to create project shader assets.
- AmplifyColor → Preview Assets: provides · Amplify Color contributes LUT and volume tooling for preview workflows.
- Gizmos → Map System: visualizes · Gizmo meshes and selectors help inspect map H-point data.
- Preview Assets → Game Shaders: configures · Preview scenes tune the appearance of project shaders.
- Mod Examples → Bundle Build: reference build · Examples act as the canonical source layout for export.