# pafuhana1213/kawaiiphysics architecture

> Architecture diagram of the GitHub repository pafuhana1213/kawaiiphysics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pafuhana1213/kawaiiphysics
- Repository: https://github.com/pafuhana1213/kawaiiphysics

## Overview

##### Project Type and Purpose
- This is an Unreal Engine C++ plugin (“KawaiiPhysics”) bundled with a sample Unreal project (“KawaiiPhysicsSample”).
- Purpose: provide a lightweight, PhysX-independent pseudo-physics system for animating “kawaii” elements (hair, skirt, etc.) via a custom AnimNode in the UE animation pipeline.

##### File Structure Analysis
- Top-level directories:
- Config: engine/project INI settings
- Content: sample maps, assets, blueprints under Content/KawaiiPhysicsSample
- Plugins: contains the KawaiiPhysics plugin
- Plugins/KawaiiPhysics:
- KawaiiPhysics.uplugin (metadata)
- Source/KawaiiPhysics: runtime module (Public/Private, Build.cs)
- Source/KawaiiPhysicsEd: editor module (graph node, edit mode)
- Sample project files: .uproject, LICENSE, README, .gitignore

##### Key Insights from README
- Two modules: Runtime and Editor
- Integrates via an AnimGraph node (`KawaiiPhysics`)
- Uses DataAssets and existing PhysicsAssets for parameter storage
- Supports external forces, collisions (sphere/capsule/plane), stable simulation
- Sample content under Content/KawaiiPhysicsSample demonstrates usage

##### Components
a. Unreal Engine Core
– Animation Subsystem (AnimGraph execution)
– Asset Management Subsystem (DataAsset, PhysicsAsset loading)
b. KawaiiPhysics Plugin
– Runtime Module (KawaiiPhysics.dll)
- AnimNode_KawaiiPhysics (C++ class)
- Physics algorithm library (KawaiiPhysicsLibrary)
- External force/constraints handlers
– Editor Module (KawaiiPhysicsEd.dll)
- AnimGraph node UI (AnimGraphNode_KawaiiPhysics)
- Edit-mode tools (KawaiiPhysicsEditMode)
c. Project Content
– Sample levels and assets (skeletal meshes, skeletons, materials under Content/KawaiiPhysicsSample)
– Blueprints (BP_Skirt, BP_GC_ExternalForce, sample game mode)
d. Data Stores
– DataAsset (BoneConstraintsDataAsset, LimitsDataAsset)

##### Relationships and Data Flows
1. At load time, UE Engine loads the plugin modules (Runtime & Editor).
2. Editor Module registers the AnimGraph node; user drags “KawaiiPhysics” node into Blueprint AnimGraph.
3. At runtime, SkeletalMeshComponent triggers the AnimGraph evaluation.
4. AnimNode_KawaiiPhysics reads:
– Current bone transforms (from animation pose)
– Parameters (from DataAsset or default node parameters)
5. AnimNode invokes the physics algorithm (computed in KawaiiPhysicsLibrary)
6. New bone transforms are output back to the AnimGraph, blending into final pose
7. If ExternalForces or AnimNotifies are defined, they feed into the algorithm each tick

##### Architectural Patterns & Principles
- Modular plugin architecture: separate Editor vs. Runtime responsibilities.
- Data-driven design: parameters in DataAssets and PhysicsAssets.
- Single-responsibility AnimNode: encapsulates physics calculation.
- Lightweight algorithm to prevent skeleton distortion, independent of PhysX.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Engine Core
    subgraph "Engine Core"
        direction TB
        AnimSub["Animation Subsystem"]:::engine
        AssetSub["Asset Management Subsystem"]:::engine
    end

    %% Plugin - Runtime Module
    subgraph "Plugin - Runtime Module" 
        direction TB
        PluginMeta["KawaiiPhysics.uplugin"]:::runtime
        BuildScript["KawaiiPhysics.Build.cs"]:::runtime
        PublicDir["Public (Headers)"]:::runtime
        PrivateDir["Private (Sources)"]:::runtime
        AnimNode["AnimNode_KawaiiPhysics"]:::runtime
        Library["KawaiiPhysicsLibrary"]:::runtime
        ExtForce1["KawaiiPhysicsExternalForce"]:::runtime
        ExtForce2["KawaiiPhysicsCustomExternalForce"]:::runtime
        subgraph "AnimNotifies"
            direction TB
            AnimNotifyX["AnimNotify_KawaiiPhysics"]:::runtime
            AnimNotifyState["AnimNotifyState_KawaiiPhysics"]:::runtime
        end
    end

    %% Plugin - Editor Module
    subgraph "Plugin - Editor Module"
        direction TB
        BuildScriptEd["KawaiiPhysicsEd.Build.cs"]:::editor
        PublicEd["Public (Headers)"]:::editor
        PrivateEd["Private (Sources)"]:::editor
        GraphNode["AnimGraphNode_KawaiiPhysics"]:::editor
        EditMode["KawaiiPhysicsEditMode"]:::editor
    end

    %% Content / Blueprints
    subgraph "Content / Blueprints"
        direction TB
        SampleLevel["L_KawaiiPhysicsSample.umap"]:::content
        BPskirt["BP_Skirt"]:::content
        BPforce["BP_GC_ExternalForce"]:::content
        BPmode["BP_SampleGameMode"]:::content
    end

    %% Configuration Assets
    subgraph "Configuration Assets"
        direction TB
        BoneDA["BoneConstraintsDataAsset"]:::assets
        LimitsDA["LimitsDataAsset"]:::assets
        ClothPA["CLOTH_SimpleCloth_PhysicsAsset"]:::assets
        GrayPA["GrayChan_PhysicsAsset"]:::assets
        KanoPA["test_kano1_PhysicsAsset"]:::assets
        ChainDefPA["S_Chain_PhysicsDefault"]:::assets
        ChainSimPA["S_Chain_PhysicsSimulated"]:::assets
    end

    %% Relationships
    AnimSub -->|"evaluates AnimGraph"| AnimNode
    AnimNode -->|"calls compute() "| Library
    Library -->|"returns transforms"| AnimNode
    BoneDA -->|"provides params"| AnimNode
    LimitsDA -->|"provides params"| AnimNode
    ClothPA -->|"collision shapes"| AnimNode
    GrayPA -->|"collision shapes"| AnimNode
    KanoPA -->|"collision shapes"| AnimNode
    ChainDefPA -->|"collision shapes"| AnimNode
    ChainSimPA -->|"collision shapes"| AnimNode
    ExtForce1 -->|"feeds forces"| Library
    ExtForce2 -->|"feeds forces"| Library
    AnimNotifyX -->|"triggers"| Library
    AnimNotifyState -->|"triggers"| Library
    AnimNode -->|"outputs pose"| AnimSub
    AssetSub -->|"loads->"| PluginMeta
    PluginMeta -->|"initializes Module"| BuildScript
    GraphNode -->|"registers Node"| AnimSub
    SampleLevel -->|"uses Plugin"| PluginMeta
    SampleLevel -->|"contains"| BPskirt
    SampleLevel -->|"contains"| BPforce
    SampleLevel -->|"contains"| BPmode

    %% Click Events - Runtime
    click PluginMeta "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Plugins/KawaiiPhysics/KawaiiPhysics.uplugin"
    click BuildScript "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Plugins/KawaiiPhysics/Source/KawaiiPhysics/KawaiiPhysics.Build.cs"
    click PublicDir "https://github.com/pafuhana1213/kawaiiphysics/tree/master/Plugins/KawaiiPhysics/Source/KawaiiPhysics/Public"
    click PrivateDir "https://github.com/pafuhana1213/kawaiiphysics/tree/master/Plugins/KawaiiPhysics/Source/KawaiiPhysics/Private"
    click AnimNode "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Plugins/KawaiiPhysics/Source/KawaiiPhysics/Private/AnimNode_KawaiiPhysics.cpp"
    click AnimNode "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Plugins/KawaiiPhysics/Source/KawaiiPhysics/Public/AnimNode_KawaiiPhysics.h"
    click Library "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Plugins/KawaiiPhysics/Source/KawaiiPhysics/Private/KawaiiPhysicsLibrary.cpp"
    click Library "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Plugins/KawaiiPhysics/Source/KawaiiPhysics/Public/KawaiiPhysicsLibrary.h"
    click ExtForce1 "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Plugins/KawaiiPhysics/Source/KawaiiPhysics/Private/KawaiiPhysicsExternalForce.cpp"
    click ExtForce1 "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Plugins/KawaiiPhysics/Source/KawaiiPhysics/Public/KawaiiPhysicsExternalForce.h"
    click ExtForce2 "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Plugins/KawaiiPhysics/Source/KawaiiPhysics/Private/KawaiiPhysicsCustomExternalForce.cpp"
    click ExtForce2 "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Plugins/KawaiiPhysics/Source/KawaiiPhysics/Public/KawaiiPhysicsCustomExternalForce.h"
    click BoneDA "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Plugins/KawaiiPhysics/Source/KawaiiPhysics/Private/KawaiiPhysicsBoneConstraintsDataAsset.cpp"
    click BoneDA "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Plugins/KawaiiPhysics/Source/KawaiiPhysics/Public/KawaiiPhysicsBoneConstraintsDataAsset.h"
    click LimitsDA "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Plugins/KawaiiPhysics/Source/KawaiiPhysics/Private/KawaiiPhysicsLimitsDataAsset.cpp"
    click LimitsDA "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Plugins/KawaiiPhysics/Source/KawaiiPhysics/Public/KawaiiPhysicsLimitsDataAsset.h"
    click AnimNotifyX "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Plugins/KawaiiPhysics/Source/KawaiiPhysics/Private/AnimNotifies/AnimNotify_KawaiiPhysics.cpp"
    click AnimNotifyX "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Plugins/KawaiiPhysics/Source/KawaiiPhysics/Public/AnimNotifies/AnimNotify_KawaiiPhysics.h"
    click AnimNotifyState "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Plugins/KawaiiPhysics/Source/KawaiiPhysics/Private/AnimNotifies/AnimNotifyState_KawaiiPhysics.cpp"
    click AnimNotifyState "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Plugins/KawaiiPhysics/Source/KawaiiPhysics/Public/AnimNotifies/AnimNotifyState_KawaiiPhysics.h"

    %% Click Events - Editor
    click BuildScriptEd "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Plugins/KawaiiPhysics/Source/KawaiiPhysicsEd/KawaiiPhysicsEd.Build.cs"
    click PublicEd "https://github.com/pafuhana1213/kawaiiphysics/tree/master/Plugins/KawaiiPhysics/Source/KawaiiPhysicsEd/Public"
    click PrivateEd "https://github.com/pafuhana1213/kawaiiphysics/tree/master/Plugins/KawaiiPhysics/Source/KawaiiPhysicsEd/Private"
    click GraphNode "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Plugins/KawaiiPhysics/Source/KawaiiPhysicsEd/Private/AnimGraphNode_KawaiiPhysics.cpp"
    click GraphNode "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Plugins/KawaiiPhysics/Source/KawaiiPhysicsEd/Public/AnimGraphNode_KawaiiPhysics.h"
    click EditMode "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Plugins/KawaiiPhysics/Source/KawaiiPhysicsEd/Private/KawaiiPhysicsEditMode.cpp"
    click EditMode "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Plugins/KawaiiPhysics/Source/KawaiiPhysicsEd/Public/KawaiiPhysicsEditMode.h"

    %% Click Events - Content
    click SampleLevel "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Content/KawaiiPhysicsSample/L_KawaiiPhysicsSample.umap"
    click BPskirt "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Content/KawaiiPhysicsSample/Model/Skirt/Blueprints/BP_Skirt.uasset"
    click BPforce "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Content/KawaiiPhysicsSample/Samples/3-Force/ABP_GC_ExternalForce.uasset"
    click BPmode "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Content/KawaiiPhysicsSample/Other/BP_SampleGameMode.uasset"

    %% Click Events - Configuration Assets
    click ClothPA "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Content/KawaiiPhysicsSample/Model/Cloth/CLOTH_SimpleCloth_PhysicsAsset.uasset"
    click GrayPA "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Content/KawaiiPhysicsSample/Model/GrayChan/Mesh/GrayChan_PhysicsAsset.uasset"
    click KanoPA "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Content/KawaiiPhysicsSample/Model/TAStyleKano/Mesh/test_kano1_PhysicsAsset.uasset"
    click ChainDefPA "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Content/KawaiiPhysicsSample/Model/Chain/S_Chain_PhysicsDefault.uasset"
    click ChainSimPA "https://github.com/pafuhana1213/kawaiiphysics/blob/master/Content/KawaiiPhysicsSample/Model/Chain/S_Chain_PhysicsSimulated.uasset"

    %% Styles
    classDef engine fill:#add8e6,stroke:#333,stroke-width:1px
    classDef runtime fill:#90ee90,stroke:#333,stroke-width:1px
    classDef editor fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef content fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef assets fill:#ffff99,stroke:#333,stroke-width:1px
```
