# ureishi/qvpen architecture

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

- Interactive diagram: https://gitdiagram.com/ureishi/qvpen
- Repository: https://github.com/ureishi/qvpen

## Overview

1. **What this repo is**
   - A Unity-based **VRChat world pen system** called **QvPen**.
   - The code is organized as a reusable Unity package under `Assets/QvPen`, with runtime prefabs, Udon scripts, shaders, meshes, materials, and a sample/world scene.

2. **Primary runtime boundary**
   - The core runtime lives in `Assets/QvPen/Runtime`.
   - C# source is split into **Udon scripts** and **UI/World scripts**, indicating this is meant for **VRChat Udon/UdonSharp-style execution** rather than a conventional Unity MonoBehaviour app.
   - The compiled/runtime Udon assets are stored separately in `Runtime/UdonAsset` and `SerializedUdonPrograms`, which is the generated layer that the scene/prefabs actually reference.

3. **Main system split: pen, eraser, manager**
   - The central interaction model is split into:
     - **Pen**: `QvPen_Pen`, `QvPen_PenManager`
     - **Eraser**: `QvPen_Eraser`, `QvPen_EraserManager`
     - **Top-level orchestration**: `QvPen_Manager`
   - This suggests a hierarchy where the manager coordinates tool modes and tool state, while pen/eraser components do the actual drawing/removal behavior.

4. **User interaction and UI layer**
   - The `Runtime/UdonScript/UI` folder contains the user-facing control scripts:
     - clear button / clear-all button
     - reset-all button
     - show/hide button
     - toggle-mode button
     - interact button
   - These likely act as thin event-driven controllers that call into the main pen/eraser managers, forming the main input-to-action boundary.

5. **World/player behavior and local state**
   - `Runtime/UdonScript/World/QvPen_PlayerMods.cs` suggests per-player or world-level behavior customization.
   - `QvPen_Settings.cs` and `QvPen_LateSync.cs` indicate there is a configuration/state layer and a synchronization layer, likely handling delayed propagation of tool state or ownership-related updates in a multiplayer VRChat context.

6. **Rendering pipeline for strokes**
   - The visual stroke system is backed by a custom shader: `Shader/rounded_trail_for_qv_pen.shader`.
   - Materials are separated by target/environment:
     - `Ink_PC.mat` and `Ink_Quest.mat`
     - multiple pen colors in `Material/Pen`
     - eraser materials in `Material/Eraser`
     - pointer/reticle materials in `Material/pointer`
     - a `wood.mat` likely used for the physical pen or scene props
   - This indicates the pen’s appearance is not just script-driven; it has a dedicated rendering/material layer with PC/Quest compatibility.

7. **Physical/scene assets**
   - `Mesh/qv_pen.fbx` and `Mesh/qv_eraser.fbx` are the main 3D models.
   - Prefabs such as `PenManager.prefab`, `EraserManager.prefab`, `QvPen.prefab`, and `QvPen(grad).prefab` are the primary composition units.
   - `QvPen.unity` is the scene-level integration point where the full system is assembled and tested.

8. **State and configuration assets**
   - The many `.asset` files in `Runtime/UdonAsset` appear to be serialized Udon program assets for each logical component.
   - `QvPen.asset`, `QvPen.version.txt`, and `QvPen.asmdef` indicate the package has a defined assembly boundary, versioning, and a distributable package identity.
   - The architecture clearly separates editable source from generated runtime data.

9. **Editor/tooling boundary**
   - `Packages/com.vrchat.core.vpm-resolver` is a bundled editor dependency for VRChat package resolution.
   - This is infrastructure for authoring/building the world package, not part of the in-world runtime.
   - The project also includes standard Unity project settings and VRChat-related package settings under `ProjectSettings`.

10. **Likely end-to-end data flow**
   - Player interacts with UI or tool objects in the world.
   - UI events go to the relevant Udon script controller.
   - Controllers delegate to manager components, which route to pen or eraser behavior.
   - Pen actions produce rendered trail/stroke output through the shader/material/mesh layer.
   - Eraser and clear/reset actions mutate or remove those stroke objects.
   - Sync/state scripts help keep behavior consistent across players in the VRChat world.

Main entry points: [`Assets/QvPen/Runtime/UdonScript/QvPen_Manager.cs`](https://github.com/ureishi/qvpen/blob/main/Assets/QvPen/Runtime/UdonScript/QvPen_Manager.cs) (Manager), [`Assets/QvPen/Runtime/UdonScript/UI`](https://github.com/ureishi/qvpen/tree/main/Assets/QvPen/Runtime/UdonScript/UI) (UI controls), [`Assets/QvPen/Runtime`](https://github.com/ureishi/qvpen/tree/main/Assets/QvPen/Runtime) (Runtime core), [`Assets/QvPen/Prefab`](https://github.com/ureishi/qvpen/tree/main/Assets/QvPen/Prefab) (Prefabs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_package["QvPen package"]
  node_qvpen_pkg["QvPen package<br/>unity package<br/>[package.json]"]
  node_qvpen_asmdef["Assembly<br/>asmdef<br/>[QvPen.asmdef]"]
end

subgraph group_runtime["Runtime"]
  node_runtime_root["Runtime core<br/>udon runtime"]
  node_udon_assets["Udon assets<br/>serialized programs"]
  node_manager(("Manager<br/>orchestrator<br/>[QvPen_Manager.cs]"))
  node_pen_mgr(("Pen manager<br/>tool coordinator"))
  node_pen(("Pen<br/>drawing tool<br/>[QvPen_Pen.cs]"))
  node_eraser_mgr(("Eraser manager<br/>tool coordinator"))
  node_eraser(("Eraser<br/>removal tool<br/>[QvPen_Eraser.cs]"))
  node_settings["Settings<br/>config state<br/>[QvPen_Settings.cs]"]
  node_latesync["Late sync<br/>sync state<br/>[QvPen_LateSync.cs]"]
  node_playermods["Player mods<br/>world behavior"]
  node_ui_layer["UI controls<br/>input controllers"]
end

subgraph group_art["Visual assets"]
  node_shader{{"Stroke shader"}}
  node_materials["Materials<br/>material set"]
  node_meshes["Meshes<br/>3d models"]
end

subgraph group_scene["Scene/prefabs"]
  node_prefabs["Prefabs<br/>composition units"]
  node_world_prefab["QvPen prefab<br/>world assembly<br/>[QvPen.prefab]"]
  node_sample_scene["Sample scene<br/>unity scene<br/>[QvPen.unity]"]
end

subgraph group_editor["Editor tooling"]
  node_vpm_resolver["VPM resolver<br/>editor tooling"]
end

node_qvpen_pkg -->|"defines"| node_qvpen_asmdef
node_qvpen_pkg -->|"contains"| node_runtime_root
node_qvpen_pkg -->|"contains"| node_prefabs
node_runtime_root -->|"generated assets"| node_udon_assets
node_runtime_root -->|"hosts"| node_manager
node_runtime_root -->|"hosts"| node_ui_layer
node_manager -->|"routes tool mode"| node_pen_mgr
node_manager -->|"routes tool mode"| node_eraser_mgr
node_pen_mgr -->|"controls"| node_pen
node_eraser_mgr -->|"controls"| node_eraser
node_ui_layer -->|"events"| node_manager
node_ui_layer -->|"mode/actions"| node_pen_mgr
node_ui_layer -->|"mode/actions"| node_eraser_mgr
node_ui_layer -->|"toggles"| node_settings
node_latesync -->|"syncs state"| node_manager
node_playermods -->|"customizes"| node_manager
node_pen -->|"renders via"| node_shader
node_pen -->|"uses"| node_materials
node_eraser -->|"uses"| node_materials
node_prefabs -->|"composes"| node_meshes
node_prefabs -->|"composes"| node_materials
node_prefabs -->|"references"| node_udon_assets
node_world_prefab -->|"includes"| node_manager
node_world_prefab -->|"includes"| node_pen_mgr
node_world_prefab -->|"includes"| node_eraser_mgr
node_sample_scene -->|"assembles"| node_world_prefab
node_vpm_resolver -.->|"supports authoring"| node_qvpen_pkg

click node_qvpen_pkg "https://github.com/ureishi/qvpen/blob/main/Assets/QvPen/package.json"
click node_qvpen_asmdef "https://github.com/ureishi/qvpen/blob/main/Assets/QvPen/QvPen.asmdef"
click node_runtime_root "https://github.com/ureishi/qvpen/tree/main/Assets/QvPen/Runtime"
click node_udon_assets "https://github.com/ureishi/qvpen/tree/main/Assets/QvPen/Runtime/UdonAsset"
click node_manager "https://github.com/ureishi/qvpen/blob/main/Assets/QvPen/Runtime/UdonScript/QvPen_Manager.cs"
click node_pen_mgr "https://github.com/ureishi/qvpen/blob/main/Assets/QvPen/Runtime/UdonScript/QvPen_PenManager.cs"
click node_pen "https://github.com/ureishi/qvpen/blob/main/Assets/QvPen/Runtime/UdonScript/QvPen_Pen.cs"
click node_eraser_mgr "https://github.com/ureishi/qvpen/blob/main/Assets/QvPen/Runtime/UdonScript/QvPen_EraserManager.cs"
click node_eraser "https://github.com/ureishi/qvpen/blob/main/Assets/QvPen/Runtime/UdonScript/QvPen_Eraser.cs"
click node_settings "https://github.com/ureishi/qvpen/blob/main/Assets/QvPen/Runtime/UdonScript/QvPen_Settings.cs"
click node_latesync "https://github.com/ureishi/qvpen/blob/main/Assets/QvPen/Runtime/UdonScript/QvPen_LateSync.cs"
click node_playermods "https://github.com/ureishi/qvpen/blob/main/Assets/QvPen/Runtime/UdonScript/World/QvPen_PlayerMods.cs"
click node_ui_layer "https://github.com/ureishi/qvpen/tree/main/Assets/QvPen/Runtime/UdonScript/UI"
click node_shader "https://github.com/ureishi/qvpen/blob/main/Assets/QvPen/Shader/rounded_trail_for_qv_pen.shader"
click node_materials "https://github.com/ureishi/qvpen/tree/main/Assets/QvPen/Material"
click node_meshes "https://github.com/ureishi/qvpen/tree/main/Assets/QvPen/Mesh"
click node_prefabs "https://github.com/ureishi/qvpen/tree/main/Assets/QvPen/Prefab"
click node_world_prefab "https://github.com/ureishi/qvpen/blob/main/Assets/QvPen/QvPen.prefab"
click node_sample_scene "https://github.com/ureishi/qvpen/blob/main/Assets/QvPen/QvPen.unity"
click node_vpm_resolver "https://github.com/ureishi/qvpen/blob/main/Packages/com.vrchat.core.vpm-resolver"

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_qvpen_pkg,node_qvpen_asmdef toneBlue
class node_runtime_root,node_udon_assets,node_manager,node_pen_mgr,node_pen,node_eraser_mgr,node_eraser,node_settings,node_latesync,node_playermods,node_ui_layer toneAmber
class node_shader,node_materials,node_meshes toneMint
class node_prefabs,node_world_prefab,node_sample_scene toneRose
class node_vpm_resolver toneIndigo
```

## Components

### QvPen package

Reusable Unity package content for the pen world system.

- [QvPen package](https://github.com/ureishi/qvpen/blob/main/Assets/QvPen/package.json): unity package · Package boundary and distributable identity for the system. · `Assets/QvPen/package.json`
- [Assembly](https://github.com/ureishi/qvpen/blob/main/Assets/QvPen/QvPen.asmdef): asmdef · C# assembly boundary for the package. · `Assets/QvPen/QvPen.asmdef`

### Runtime

In-world Udon runtime scripts and generated program assets.

- [Runtime core](https://github.com/ureishi/qvpen/tree/main/Assets/QvPen/Runtime): udon runtime · Main in-world execution boundary for the pen system. · `Assets/QvPen/Runtime`
- [Udon assets](https://github.com/ureishi/qvpen/tree/main/Assets/QvPen/Runtime/UdonAsset): serialized programs · Generated Udon program assets referenced by prefabs and scene objects. · `Assets/QvPen/Runtime/UdonAsset`
- [Manager](https://github.com/ureishi/qvpen/blob/main/Assets/QvPen/Runtime/UdonScript/QvPen_Manager.cs): orchestrator · Top-level coordination for tool modes and shared state. · `Assets/QvPen/Runtime/UdonScript/QvPen_Manager.cs`
- [Pen manager](https://github.com/ureishi/qvpen/blob/main/Assets/QvPen/Runtime/UdonScript/QvPen_PenManager.cs): tool coordinator · Coordinates pen tool behavior and state. · `Assets/QvPen/Runtime/UdonScript/QvPen_PenManager.cs`
- [Pen](https://github.com/ureishi/qvpen/blob/main/Assets/QvPen/Runtime/UdonScript/QvPen_Pen.cs): drawing tool · Core drawing behavior that creates strokes and ink output. · `Assets/QvPen/Runtime/UdonScript/QvPen_Pen.cs`
- [Eraser manager](https://github.com/ureishi/qvpen/blob/main/Assets/QvPen/Runtime/UdonScript/QvPen_EraserManager.cs): tool coordinator · Coordinates eraser behavior and state. · `Assets/QvPen/Runtime/UdonScript/QvPen_EraserManager.cs`
- [Eraser](https://github.com/ureishi/qvpen/blob/main/Assets/QvPen/Runtime/UdonScript/QvPen_Eraser.cs): removal tool · Core erase behavior for removing strokes. · `Assets/QvPen/Runtime/UdonScript/QvPen_Eraser.cs`
- [Settings](https://github.com/ureishi/qvpen/blob/main/Assets/QvPen/Runtime/UdonScript/QvPen_Settings.cs): config state · Shared configuration and runtime options for the system. · `Assets/QvPen/Runtime/UdonScript/QvPen_Settings.cs`
- [Late sync](https://github.com/ureishi/qvpen/blob/main/Assets/QvPen/Runtime/UdonScript/QvPen_LateSync.cs): sync state · Delayed synchronization layer for multiplayer/world state updates. · `Assets/QvPen/Runtime/UdonScript/QvPen_LateSync.cs`
- [Player mods](https://github.com/ureishi/qvpen/blob/main/Assets/QvPen/Runtime/UdonScript/World/QvPen_PlayerMods.cs): world behavior · Per-player or world-level behavior customization hooks. · `Assets/QvPen/Runtime/UdonScript/World/QvPen_PlayerMods.cs`
- [UI controls](https://github.com/ureishi/qvpen/tree/main/Assets/QvPen/Runtime/UdonScript/UI): input controllers · World UI scripts that forward user actions into tool managers. · `Assets/QvPen/Runtime/UdonScript/UI`

### Visual assets

Meshes, materials, shader, and textures used by the pen system.

- [Stroke shader](https://github.com/ureishi/qvpen/blob/main/Assets/QvPen/Shader/rounded_trail_for_qv_pen.shader): shader · Custom trail shader used to render pen strokes. · `Assets/QvPen/Shader/rounded_trail_for_qv_pen.shader`
- [Materials](https://github.com/ureishi/qvpen/tree/main/Assets/QvPen/Material): material set · Ink, pen, eraser, pointer, and wood materials for visual variants. · `Assets/QvPen/Material`
- [Meshes](https://github.com/ureishi/qvpen/tree/main/Assets/QvPen/Mesh): 3d models · Main physical models for the pen and eraser props. · `Assets/QvPen/Mesh`

### Scene/prefabs

Prefab and scene assembly points that compose the runtime.

- [Prefabs](https://github.com/ureishi/qvpen/tree/main/Assets/QvPen/Prefab): composition units · Reusable prefab compositions for pen and eraser managers and world objects. · `Assets/QvPen/Prefab`
- [QvPen prefab](https://github.com/ureishi/qvpen/blob/main/Assets/QvPen/QvPen.prefab): world assembly · Primary assembled world object for the pen system. · `Assets/QvPen/QvPen.prefab`
- [Sample scene](https://github.com/ureishi/qvpen/blob/main/Assets/QvPen/QvPen.unity): unity scene · Scene-level integration and test assembly for the full system. · `Assets/QvPen/QvPen.unity`

### Editor tooling

Bundled VRChat package resolver/editor infrastructure.

- [VPM resolver](https://github.com/ureishi/qvpen/blob/main/Packages/com.vrchat.core.vpm-resolver): editor tooling · Bundled VRChat package resolution and authoring support. · `Packages/com.vrchat.core.vpm-resolver`

## Connections

- QvPen package → Assembly: defines · Package boundary is implemented through a dedicated assembly.
- QvPen package → Runtime core: contains · Package includes the runtime execution layer.
- QvPen package → Prefabs: contains · Package ships prefab composition units.
- Runtime core → Udon assets: generated assets · Source scripts are paired with serialized Udon program assets.
- Runtime core → Manager: hosts · Runtime root contains the main orchestration script.
- Runtime core → UI controls: hosts · Runtime root contains user-facing control scripts.
- Manager → Pen manager: routes tool mode · Top-level manager delegates pen mode control.
- Manager → Eraser manager: routes tool mode · Top-level manager delegates eraser mode control.
- Pen manager → Pen: controls · Pen manager coordinates drawing behavior.
- Eraser manager → Eraser: controls · Eraser manager coordinates removal behavior.
- UI controls → Manager: events · UI actions forward into orchestration/state changes.
- UI controls → Pen manager: mode/actions · Tool buttons interact with pen controls.
- UI controls → Eraser manager: mode/actions · Tool buttons interact with eraser controls.
- UI controls → Settings: toggles · UI can adjust shared configuration/state.
- Late sync → Manager: syncs state · Synchronization layer keeps shared runtime state consistent.
- Player mods → Manager: customizes · Player/world behavior hooks affect orchestration.
- Pen → Stroke shader: renders via · Stroke output depends on the custom trail shader.
- Pen → Materials: uses · Pen drawing relies on ink and color materials.
- Eraser → Materials: uses · Eraser visuals rely on eraser materials.
- Prefabs → Meshes: composes · Prefabs assemble the pen and eraser meshes.
- Prefabs → Materials: composes · Prefabs bind visual material variants.
- Prefabs → Udon assets: references · Prefab instances reference serialized Udon programs.
- QvPen prefab → Manager: includes · Primary world prefab includes the orchestration component.
- QvPen prefab → Pen manager: includes · Primary world prefab includes pen management.
- QvPen prefab → Eraser manager: includes · Primary world prefab includes eraser management.
- Sample scene → QvPen prefab: assembles · Scene composes the full world object for testing/integration.
- VPM resolver → QvPen package: supports authoring · Editor tooling supports package resolution and packaging.
