How mof-mal/csharpblock4unity works
1. What this repo is
- A single-page, browser-based visual programming editor for generating C# code from Blockly blocks.
- The app is entirely client-side: React + TypeScript + Vite, with Blockly as the visual engine and a custom C# codegen layer.
2. Top-level application shape
- src/main.tsx bootstraps the app.
- src/App.tsx is the root shell.
- The main editor experience lives under src/pages/editor-page/, which acts as the composition layer for the whole product.
3. Primary screen composition
- The editor page combines several feature modules:
- header for top-level actions/navigation
- workspace-tabs for switching between multiple scripts/workspaces
- block-canvas for the Blockly editing surface
- code-preview for generated C# output
- chain-menu for block-chain insertion/interaction affordances
- autosave for persistence behavior
- This is the main UI boundary: page-level orchestration vs feature-level implementation.
4. Blockly integration layer
- The src/util/blockly/ directory is the core integration boundary around Blockly.
- It contains custom block creation, toolbox construction, mutator registration, connection/type checking, shadow blocks, and helpers for chain/block behavior.
- This layer is responsible for turning the app’s schema and domain rules into a Blockly workspace that behaves consistently.
5. Schema-driven block model
- src/assets/schema/ holds JSON schema fragments such as engineCore.json, variables.json, operators.json, event.json, and others.
- src/util/schema/ loads, validates, and namespaces these schemas.
- The schema layer is the source of truth for what blocks exist, how they are grouped, and what types or namespaces they belong to.
6. Type and definition model
- src/types/ defines the repository’s domain contracts: block definitions, workspace state, schema shape, and codegen-related types.
- These types are shared across schema parsing, Blockly setup, workspace management, and code generation to keep the system aligned.
7. Code generation pipeline
- src/util/codegen/ is the output side of the architecture.
- It converts the block/workspace model into formatted C# via custom generators and a C# formatter.
- The code preview feature depends on this pipeline to render live output as the user edits blocks.
8. Workspace and autosave behavior
- src/features/workspace-tabs/ manages multiple editable workspaces, including tab state and switching logic.
- src/features/autosave/ provides persistence of editor state, likely backed by browser storage; the presence of localStrageSample.json suggests local serialized workspace data is a key runtime artifact.
- Together, these features define how editing sessions survive and how multiple scripts are handled in one browser session.
9. User interaction features
- chain-menu and its hook (useDotMenu) suggest specialized contextual editing for chaining blocks or inserting connected actions.
- block-canvas/customTheme.ts and src/shared/ui/ToolbarButton.tsx indicate a small shared UI layer plus Blockly-specific theming for consistent editor behavior.
10. Runtime data flow
- The practical flow is:
- JSON schemas define available block families and types
- Blockly utilities build/register those blocks and toolbox entries
- The user assembles blocks in the canvas
- Workspace state is updated and optionally autosaved
- The codegen layer translates the workspace into C#
- The preview panel renders the generated code in real time
11. Boundary between presentation and domain logic
- src/features/ contains user-facing capabilities and UI composition.
- src/util/ contains the heavier domain logic: Blockly customization, schema interpretation, and code generation.
- This separation is important for diagramming: the editor UI is not where the block semantics live; those rules are centralized in utilities and schema assets.
12. Build, tooling, and delivery
- Vite handles bundling and dev server operation.
- ESLint, Prettier, and Husky indicate enforced code quality via local git hooks.
- The GitHub Actions workflow under .github/workflows/static.yml suggests static build/deploy automation for the compiled client app.
13. How to think about the architecture diagram
- Draw it as a browser-based editor with three main layers:
- UI composition: page + features
- Domain engine: Blockly/schema/type/codegen utilities
- Static assets and config: schemas, icons, app config
- The central integration point is the Blockly workspace, which connects user interaction to the generated C# output and persistence features.
Main entry points: ui.tsx Page UI · editor-page/index.tsx Editor page · blockly Blockly integration · block-canvas/index.tsx Block canvas
Components 19
App Shell
Bootstrapping and top-level page composition for the client app.
Editor UI
User-facing editor features assembled on the main screen.
- Editor page · Main composition layer that wires together the editing experience.
src/pages/editor-page/index.tsx - Page UI · Editor page presentation and layout boundaries.
src/pages/editor-page/ui.tsx - Page model · State and orchestration logic behind the editor page.
src/pages/editor-page/model.ts - Header · Top-level actions and navigation for the editor.
src/features/header/index.tsx - Workspace tabs · Switches between multiple workspaces or scripts.
src/features/workspace-tabs/index.tsx - Block canvas · Blockly editing surface and theme integration.
src/features/block-canvas/index.tsx - Chain menu · Contextual chain insertion and block interaction affordances.
src/features/chain-menu/index.tsx - Code preview · Renders generated C# output as the user edits blocks.
src/features/code-preview/index.tsx - Autosave · Persists editor state across sessions.
src/features/autosave/index.ts - Shared UI · Reusable UI controls shared across the editor.
src/shared/ui
Domain Engine
Schema, Blockly integration, workspace model, and C# code generation.
- Blockly integration · Custom Blockly setup for block creation, workspace behavior, and toolbox assembly.
src/util/blockly - Schema loader · Loads, validates, and namespaces schema definitions.
src/util/schema - C# codegen · Transforms workspace blocks into formatted C# output.
src/util/codegen - Domain types · Shared type definitions for blocks, schema, workspace, and codegen.
src/types - App config · Client application configuration and runtime settings.
src/app/config/appConfig.ts
Static Assets
Schema fragments and other static runtime inputs.
- Block schemas · JSON schema fragments defining available block families and namespaces.
src/assets/schema
Tooling
Build, quality, and delivery configuration.
- Build & deploy · Vite bundling, linting, hooks, and static deployment automation.
Connections 24
- main.tsx → App shell: mounts · Bootstraps the React shell.
- App shell → Editor page: renders · The app shell hosts the editor experience.
- Editor page → Page UI: composes · Page composition delegates to a UI layer.
- Editor page → Page model: orchestrates · Page logic manages editor state and coordination.
- Page UI → Header: includes · Top-level actions are part of the editor layout.
- Page UI → Workspace tabs: includes · Workspace switching is embedded in the screen.
- Page UI → Block canvas: includes · Blockly canvas is the main editing surface.
- Page UI → Chain menu: includes · Contextual chain interactions support block editing.
- Page UI → Code preview: includes · Code output is shown alongside the canvas.
- Editor page → Autosave: persists · Session state is saved from the editor boundary.
- Block canvas → Blockly integration: uses · The canvas is backed by custom Blockly integration.
- Chain menu → Blockly integration: extends · Chain interactions operate on Blockly workspace behavior.
- Blockly integration → Schema loader: loads schema from · Blockly setup is driven by normalized schema data.
- Schema loader → Block schemas: reads · Schema utilities consume JSON schema fragments.
- Blockly integration → Domain types: conforms to · Block and workspace behavior uses shared contracts.
- C# codegen → Domain types: conforms to · Code generation consumes shared workspace and block types.
- Code preview → C# codegen: renders output from · The preview panel displays generated C# code.
- Autosave → Domain types: stores · Persisted workspace state follows shared workspace types.
- Shared UI → Header: supports · Shared controls are used by editor-facing features.
- Shared UI → Block canvas: supports · Reusable UI primitives support the editor surface.
- Blockly integration → C# codegen: feeds · Workspace edits flow into the generation pipeline.
- App config → Editor page: configures · App settings influence editor startup and behavior.
- Build & deploy → main.tsx: delivers · Tooling packages and serves the client application.
- Build & deploy → Block schemas: bundles · Static schema assets are included in the app build.