📚 Vulfram Documentation Index

Welcome to the Vulfram documentation! This index will guide you to the right documents based on your needs.

🎯 Quick Navigation

I want to...

• Understand Vulfram's design → Start with OVERVIEW.md
• Create a language binding → Read ABI.md and ARCH.md
• Contribute to the Rust core → Check API.md and GLOSSARY.md
• Define a render graph → Read RENDER-GRAPH.md
• Learn terminology → See GLOSSARY.md
• Understand the architecture → Read ARCH.md
• Understand platform separation → Read PLATFORM-PROXIES.md
• Understand automated vs manual quality validation → Read VALIDATION.md

📖 Documentation Structure

For Engine Users (Binding Authors & Integrators)

If you're building a language binding (Node.js, Lua, Python, etc.) or integrating Vulfram into your application:

1. OVERVIEW.md - Start here!

   • Design goals and philosophy
   • High-level architecture
   • Components vs Resources
   • IDs and handles
   • Layer masking system

2. ABI.md - Essential for bindings

   • C-ABI function reference
   • Calling conventions
   • Error handling
   • MessagePack serialization
   • Buffer management (upload)

3. ARCH.md - Implementation patterns

   • Lifecycle management
   • Main loop structure
   • Recommended frame flow
   • Host responsibilities
   • Upload system

4. REALM-ARCH.md - Realm/Surface/RealmGraph base plan

   • Contratos e lifecycle
   • IDs lógicos e generation
   • Buffering e PreviousFrame
   • Composição multi-janela
   • Regras de rect e profiling

5. cmds/ - Command Reference

   • Detailed documentation for every engine command (Window, Camera, Model, Light, etc.)

6. RENDER-GRAPH.md - Host-defined render graph

7. ui/README.md - UI Runtime (RealmUI)

   • Arquitetura do runtime UI
   • Widgets suportados
   • Eventos, painter e limitações
   • Migração de API UI

8. GLOSSARY.md - Terminology reference

   • Core concepts (Host, Core, ABI)
   • Components vs Resources
   • IDs and handles
   • Naming conventions

9. VALIDATION.md - Quality validation strategy

   • Automated CI checks
   • Unit-test coverage scope
   • Manual validation scope via demos

For Core Contributors (Rust Developers)

If you're working on the Rust core implementation:

1. OVERVIEW.md - Foundational concepts

   • Design principles
   • Architecture overview
   • Component and resource model

2. ARCH.md - System architecture

   • Component lifecycle
   • Resource management
   • Visibility and layer masking

3. API.md - Internal implementation

   • Crate dependencies
   • Engine state structure
   • Resource and component tables
   • Command flow
   • Upload handling
   • Rendering system
   • Event system
   • Profiling data

4. GLOSSARY.md - Internal terminology

   • Function naming patterns
   • Internal handles
   • Queue types
   • File organization

🔍 Document Details

[OVERVIEW.md](/vulfram/docs/overview)

Purpose: High-level introduction to Vulfram
Audience: Everyone (start here)
Topics:

• Design goals (host-agnostic, minimal surface, binary communication)
• Architecture diagram (Host → Core → GPU)
• Components vs Resources
• Logical IDs and internal handles
• One-shot upload system
• Layer masking for visibility
• What the host sees vs. what it doesn't
• Asynchronous resource linking (fallback-driven)

[ABI.md](/vulfram/docs/abi)

Purpose: C-ABI specification and usage contract
Audience: Binding authors, advanced users
Topics:

• Return codes (VulframResult)
• Threading and reentrancy rules
• MessagePack serialization
• Output buffer management
• Function reference:
  • vulfram_init() / vulfram_dispose()
  • vulfram_send_queue()
  • vulfram_receive_queue()
  • vulfram_receive_events()
  • vulfram_upload_buffer()
  • vulfram_tick()
  • vulfram_get_profiling()
• Recommended frame loop
• Error handling guidelines

[ARCH.md](/vulfram/docs/arch)

Purpose: Architecture, lifecycle, and main loop patterns
Audience: Binding authors, integrators
Topics:

• High-level architecture
• Host vs Core responsibilities
• Components, Resources, and Instances
• Layer masking and visibility
• Core lifecycle (startup, loading, main loop, shutdown)
• Recommended main loop structure
• One-shot upload pattern and cleanup

[API.md](/vulfram/docs/api)

Purpose: Internal Rust API documentation
Audience: Core contributors (Rust developers)
Topics:

• Crate dependencies (winit, wgpu, gilrs, serde, etc.)
• Engine state structure
• Resource management (Geometries, Textures, Materials)
• Component instances (Cameras, Meshes)
• Internal command flow
• Upload table handling
• Rendering system (buffers, pipelines, render passes)
• Event system integration
• Profiling data collection

[GLOSSARY.md](/vulfram/docs/glossary)

Purpose: Terminology and naming conventions
Audience: Everyone (reference guide)
Topics:

• Core concepts (Host, Core, ABI)
• Components vs Resources
• Logical IDs vs Internal Handles
• Upload and buffer terminology
• Queue types (command, response, event)
• Layer masking
• Function naming (vulfram_*)
• Documentation file structure

🎓 Learning Paths

Path 1: Node.js Binding Developer (N-API)

OVERVIEW.md
    ↓
ABI.md (focus on N-API patterns)
    ↓
ARCH.md (main loop implementation)
    ↓
GLOSSARY.md (reference as needed)

Path 2: Python/Lua Binding Developer

OVERVIEW.md
    ↓
ABI.md (focus on FFI patterns)
    ↓
ARCH.md (lifecycle and loop)
    ↓
GLOSSARY.md (reference as needed)

Path 3: Rust Core Contributor

OVERVIEW.md
    ↓
ARCH.md
    ↓
API.md (deep dive into internals)
    ↓
GLOSSARY.md (naming conventions)

Path 4: Game Developer (Using Existing Binding)

OVERVIEW.md (optional, for understanding)
    ↓
Language-specific binding documentation
    ↓
GLOSSARY.md (for terminology)

🔗 External Resources

• README.md - Project overview and quick start
• MASCOT-DEFINITION.md - Brand guidelines
• UI.md - UI technical index
• PLATFORM-PROXIES.md - Platform proxy architecture
• Copilot Instructions - Development patterns

📝 Document Conventions

Code Examples

• Conceptual: Pseudo-code for clarity
• Rust: Actual or near-actual Rust code
• C: C-ABI function signatures
• MessagePack: Logical structure (not binary)

Terminology

• Host: External program calling Vulfram
• Core: The Rust library (Vulfram itself)
• Component: Scene entity behavior (Camera, Model, etc.)
• Resource: Reusable asset (Geometry, Texture, Material, etc.)
• Logical ID: Integer ID visible to host
• Handle: Internal core reference (not exposed)

💡 Tips for Reading

1. Start with OVERVIEW.md - It provides essential context for everything else
2. Use GLOSSARY.md - Keep it open as a reference for terminology
3. Focus on your role - Follow the learning path that matches your needs
4. Cross-reference - Documents link to each other for deeper dives
5. Check examples - Code samples demonstrate concepts in practice

🤔 Need Help?

• Found an error? Open an issue on GitHub
• Need clarification? Check GLOSSARY.md or ask in discussions
• Contributing? See CONTRIBUTING guidelines