# User Guide — 3D Magic Circle Animation Generator

This guide covers everything from basic usage to practical production workflows.

---

## Table of Contents

1. Introduction
2. UI Layout
3. Basic Workflow
4. Project Library
5. Building a Magic Circle
6. Layer Types
7. Color Themes and Layer Colors
8. Animation
9. Multiple Magic Circles
10. Export
11. Presets (Base 10)
12. Keyboard Shortcuts
13. Importing into Game Engines
14. FAQ

---

## 1) Introduction

3D Magic Circle Animation Generator is a procedural tool that combines rings, geometric shapes, runes, and effects into animated magic circles.

You can tweak parameters in real time and export assets for games, motion graphics, and illustrations.

---

## 2) UI Layout

The app has three resizable panels:
- Left: Library panel (saved projects)
- Center: 3D viewer
- Right: Editor panel (settings)

### Viewer controls
- Left drag: orbit camera
- Right drag: pan
- Mouse wheel: zoom

---

## 3) Basic Workflow

1. Select a preset (base collection: 10 presets).
2. Adjust layer parameters.
3. Add/remove/reorder/duplicate layers.
4. Save to library (`Ctrl+S`).
5. Export in your required format.

Additional collections (DLC-style presets) can be loaded via JSON import.

---

## 4) Project Library

Library data is saved locally.

- New: create a new project
- Save: save current project
- Click item: load project
- Rename project: pencil button in the library row
- Duplicate / Delete: per-item action buttons

Undo/Redo supports up to 50 steps (`Ctrl+Z`, `Ctrl+Y`, `Ctrl+Shift+Z`).

---

## 5) Building a Magic Circle

A magic circle is a container with child layers.

Example:
- Ring: Band
- Shape: Hexagram
- Rune: Ring
- Effect: Particles
- Effect: Aura

### Magic circle name editing
Double-click a magic circle header (`MagicCircle: ...`) in the editor to rename it inline.
- Enter: commit
- Esc: cancel

### Color behavior
Each non-container layer has:
- Color Role: `Main` or `Sub`
- Use Custom Layer Color: if enabled, layer color overrides role-based color

Container-level settings (`Base Color` / `Sub Color`) provide theme colors for child layers.

#### Circle Background

Fills only the interior of the magic circle with a solid or semi-transparent color disc. Configure under `Circle Settings > Circle Background`.

| Setting | Description |
|---------|-------------|
| **Enable** | Show the background disc |
| **Color** | Fill color (color picker) |
| **Opacity** | 0 (fully transparent) — 1 (fully opaque) |

**Use cases:**
- **Portal / warp gate** — Set the interior to deep black or dark purple to create a convincing "hole in space"
- **Terrain noise reduction** — A semi-transparent dark overlay makes intricate rune patterns stand out on complex terrain in game engines
- **UI icon / badge** — A filled circle prevents interference with underlying UI elements

> **Tip:** Works independently of `Transparent Background (PNG Only)`. You can combine them — e.g. fill the interior with a color while keeping the exterior transparent in PNG exports.

---

## 6) Layer Types

### Ring

| Style | Description |
|-------|-------------|
| **Band** | Simple band ring |
| **Double** | Double ring (adjustable line width and gap) |
| **Ornate** | Decorated ring with ticks (adjustable line width, gap, and tick count) |

**Parameters available for all ring styles:**
- **Arc Start Angle / Arc Angle** — Display the ring as an arc rather than a full circle. Reducing `Arc Angle` creates semicircles, quarter circles, etc.

**Double / Ornate only:**
- **Line Width** — Thickness of each ring band in world units (mesh-based to bypass the WebGL linewidth limit)
- **Line Gap** — Distance between the two ring bands
- **Tick Count** (Ornate only) — Number of tick marks along the ring

### Shape

| Style | Description |
|-------|-------------|
| **Polygon** | Regular polygon (adjustable sides) |
| **Circle** | Circle |
| **Hexagram** | Star of David (dual polygon) |
| **Pentagram** | Star (adjustable points and step) |
| **Flower** | Flower of Life |
| **Spirograph** | Spirograph / epicycloid |

**Parameter available for all shape styles:**
- **Dashed** — Switches from solid to dashed lines. Adjust `Dash Size` and `Gap Size` to control the pattern. (Line thickness is 1 px due to WebGL limitations.)

### Rune

| Style | Description |
|-------|-------------|
| **Ring** | Rune glyphs (vertical spine + random branches) arranged in a ring |
| **Bits** | Digital bit pattern |
| **Box** | Rectangle outline with random appendages extending from the sides, arranged in a ring |

> **Tip:** Ring and Box styles have a `Text Pattern Seed`. Changing the value randomizes glyph shapes; the same seed always produces identical results.

### Effect

| Style | Description |
|-------|-------------|
| **Particles** | Floating particles |
| **Aura** | Glow disc surrounding the circle |
| **Core** | Central glow disc |
| **LightPillar** | Summoning beam rising upward from the circle center |
| **BurstRays** | Radial triangular light beams arranged in a star pattern |
| **RisingOrbs** | Glowing orbs that rise and fade in a looping animation |

**LightPillar parameters:**

| Parameter | Description |
|-----------|-------------|
| **Pillar Height** | Length of the beam (0.5–20) |
| **Pillar Width** | Radius of the beam (0.05–8.0); can be wide enough to wrap around the outer ring |
| **Glow Layers (0–2)** | 0 = core only / 1 = +mid glow / 2 = +outer glow (default) |
| **Opacity** | Overall transparency (0–1) |

---

## 7) Color Themes and Layer Colors

Color themes apply container base/sub colors quickly (Fire, Ice, Dark, Holy, Poison, Gold, Blood, Forest, Storm, Cosmic, Custom).

After applying a theme, you can still fine-tune colors.

---

## 8) Animation

### Layer animation
- Rotate speed
- Orbit speed / radius / phase
- Pulse enable / speed / magnitude
- Optional speed curve (`sine`)

### Container animation
- None
- Rise
- Drop
- Slide Left
- Slide Right
- Deploy (from custom start position)
- Orbit
- Post Orbit (after intro motion)

For rise/drop/slide: distance, duration, delay, easing.
For deploy: start X/Y/Z + optional Post Orbit.

---

## 9) Multiple Magic Circles

- Add multiple circles in one scene.
- Adjust each circle position (X/Y/Z).
- Use vertical stacking with adjustable spacing.
- Drag move mode allows direct positioning in viewer.
- Add satellite circles for nested compositions.

---

## 10) Export

Available export formats:
- GLB (animated clips)
- Blender GLB Package (ZIP with GLB + auto-setup script)
- Unity Package (`.unitypackage` — PRO only)
- PNG (top view)
- Side-view PNG
- Texture PNG
- PNG sequence (ZIP)
- Sprite sheet (ZIP)
- GIF animation — top view (PRO only)
- GIF animation — side view (PRO only)
- WebM video / VP9 alpha — top view (PRO only)
- WebM video / VP9 alpha — side view (PRO only)
- MP4 video / H.264 — top view (PRO only)
- MP4 video / H.264 — side view (PRO only)
- JSON (save/load config)

### Video Export (PRO)

Export animated video from the `Video Export` folder in the PNG panel.

| Format | Codec | Alpha | Notes |
|--------|-------|-------|-------|
| **GIF** | GIF 256-color + 1-bit alpha | ✓ (when transparent BG is ON) | Loops, 256-color limit |
| **WebM** | VP9 | ✓ (when transparent BG is ON) | Full alpha channel video |
| **MP4** | H.264 | ✗ | Best compatibility; falls back to VP9 WebM if unsupported |

Each format has two view variants:

| Button | View |
|--------|------|
| Export GIF / WebM / MP4 | Top-down view |
| Side View GIF / WebM / MP4 | Perspective side view |

Settings:
- **Animation Duration (s)** — Output video length in seconds
- **Video FPS** — Frame rate (10–60 fps); affects smoothness, not duration

### Sprite Sheet Presets

The sprite sheet export supports engine-specific presets that automatically set resolution and column count:

| Preset | Resolution | Columns | Use Case |
|--------|-----------|---------|----------|
| **Custom** | PNG Resolution setting | Column slider | Free configuration |
| **RPG Maker MV/MZ** | 192 px | 5 | RPG Maker MV/MZ battle animation standard |
| **Bakin 512** | 512 px | 6 | RPG Developer Bakin (high quality) |
| **Bakin 256** | 256 px | 6 | RPG Developer Bakin (lightweight) |

When a preset other than Custom is selected, the column count slider is hidden and resolution/columns are set automatically.

### Unity Package (PRO)

Exports a `.unitypackage` ready for direct import into Unity.

**Import steps:**
1. `Assets > Import Package > Custom Package...`
2. Select the exported `.unitypackage` file
3. Click `Import`

PNG-related shared settings:
- `PNG Resolution`
- `Transparent Background (PNG Only)`
- `Visibility Boost (PNG Only)` with `None / Weak / Medium / Strong / Custom`
- `Boost Opacity Scale / Boost Min Opacity / Boost Additive Cap (PNG Only)` for `Custom` mode

`Transparent Background (PNG Only)` and `Visibility Boost (PNG Only)` are applied to PNG, PNG sequence, and sprite sheet exports.

For Blender users, the package export is recommended when actions appear split per node after import. The included script auto-assigns actions to objects and pushes strips to NLA.

`Animation Duration (s)` and `Frame Count` are also applied to GLB animation baking length and sampling density.

### Experimental: Single-Object Vertex-Baked GLB

The experimental vertex-baked export and loop/FPS options are shown when **Developer Mode (Experimental)** is enabled.
For regular workflows, the standard GLB export or Blender GLB Package is still recommended.

### GLB Export Limitations (Differences from Viewer)

Due to the GLTF/GLB format specification, the following differences exist between the in-app viewer and the exported GLB:

| Feature | Viewer | GLB |
|---------|--------|-----|
| **Additive blending (glow)** | Overlapping elements accumulate additively, creating a glow effect | Exported as standard alpha blending. Colors and opacity are preserved, but the glow from overlapping elements is lost |
| **Dashed lines (Shape dash toggle)** | Displayed with dash and gap lengths as configured | Baked into geometry — reproduced accurately in GLB |
| **Mask effect (Effect: Mask)** | Stencil-based clipping of content inside/outside a radius | GLTF does not support stencil; the mask circle is removed and all masked content is shown without clipping |
| **FadeIn animation** | Opacity animates from 0 to 1 | Approximated as a scale animation from 0 to 1 |
| **DrawOn animation** | Lines are progressively drawn | Approximated using per-segment scale animation |

> **Tip:** If preserving the glow effect is important, **transparent PNG sequence**, **sprite sheet**, or **video** exports most closely match the in-app viewer appearance.

---

## 11) Presets (Base 10)

The editor directly exposes these 10 presets:
- Classic
- Runic
- Demonic
- Grand
- Celestial
- Chrono
- Cyber
- Bloom
- Celtic
- Dense

---

## 12) Keyboard Shortcuts

- `Ctrl+Z`: Undo
- `Ctrl+Y` / `Ctrl+Shift+Z`: Redo
- `Ctrl+S`: Save to library
- `Ctrl+Shift+E`: Export GLB

---

## 13) Importing into Game Engines

### Unity
- **Unity Package (recommended)** — Import `.unitypackage` via `Assets > Import Package > Custom Package...`
- **GLB (direct)** — Import `.glb` and choose clips in Animator
- Use PNG/sprite sheets for UI or VFX

### Unreal Engine
- Import GLB via glTF importer
- Use PNG sequence as flipbook source

### Godot
- Import GLB and use clips via AnimationPlayer
- Use sprite sheet in AnimatedSprite2D

### Blender
- Import GLB
- Inspect clips in NLA editor

---

## 14) FAQ

### Where is my data saved?
Locally (browser/WebView storage). Export JSON for backups.

### Can I use generated assets commercially?
Yes, generated outputs can be used commercially. Redistribution of the software itself is prohibited.

### How are Main/Sub colors chosen?
By each layer’s `Color Role` setting. If `Use Custom Layer Color` is enabled, that custom color takes precedence.

### My animation is not moving
Check non-zero animation values and use `Replay Intro` for container animation restart.
