📚 Vulfram Documentation Index

This site is split into two documentation tracks:

• Core Docs: the Rust engine, C-ABI, and command system.
• TypeScript Binding Docs: a higher-level API for app developers.

If you are new, start with the Core Overview and follow the path that matches your role.

🎯 Quick Navigation

I want to...

• Understand what Vulfram is → Start with Overview
• Build a language binding → Read ABI Reference and Architecture
• Use the TypeScript binding → Start at TS Binding Overview
• Understand runtime separation → Read Platform Proxies
• Contribute to the core → Check Internal API and Glossary
• Look up a command → Jump to any page under Command Reference
• Customize rendering → Read Render Graph

📖 Documentation Map

Core Docs (Binding Authors & Integrators)

1. Overview

   • Mental model of host vs core
   • Components vs resources
   • IDs, uploads, and fallback semantics

2. ABI Reference

   • C-ABI functions and contracts
   • MessagePack boundaries
   • Output buffer ownership
   • Recommended frame loop

3. Architecture

   • Lifecycle and main loop structure
   • Command processing flow
   • Resource linking and batching

4. Command Reference

   • Per-command payloads, responses, and usage notes

5. Glossary

   • Terminology and naming conventions

6. Render Graph

   • Host-defined render sequence
   • Validation rules and fallback behavior

Core Docs (Rust Contributors)

1. Overview
2. Architecture
3. Internal API
4. Glossary
5. Platform Proxies
6. Render Graph

🧭 Core Command Reference Map

Commands are grouped by intent and are intentionally small. Use the reference pages when you need exact fields and response shapes.

• Window: Create, state, size, cursor, attention, focus, icons
• Camera: Create, update, list, dispose
• Model: Create, update, list, dispose
• Light: Create, update, list, dispose
• Material: Create, update, list, dispose
• Texture: Create, list, dispose
• Geometry: Create, update, list, dispose
• Primitive Geometry: Quickly generate cube/sphere/etc.
• Shadow: Configure global shadow behavior
• Render Graph: Host-defined render sequence per window
• Gizmo: Debug draw line/AABB
• Maintenance: Upload cleanup (CmdUploadBufferDiscardAll)

🎓 Suggested Learning Paths (Core)

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

/vulfram/docs/overview
    ↓
/vulfram/docs/abi
    ↓
/vulfram/docs/arch
    ↓
/vulfram/docs/glossary

Path 2: Python/Lua Binding Developer

/vulfram/docs/overview
    ↓
/vulfram/docs/abi
    ↓
/vulfram/docs/arch
    ↓
/vulfram/docs/glossary

Path 3: Rust Core Contributor

/vulfram/docs/overview
    ↓
/vulfram/docs/arch
    ↓
/vulfram/docs/api
    ↓
/vulfram/docs/glossary

📝 Conventions Used in Docs

• MessagePack examples show the logical structure, not the binary layout.
• Code blocks are conceptual unless stated otherwise.
• IDs are always host-chosen integers (opaque to the core).

🧪 TypeScript Binding Docs

• Overview
• Setup
• Core API Map
• Examples
• Troubleshooting

🔗 External References

• Project Overview: Vulfram README
• Brand & UI: Mascot (Vulfi), Visual Identity
• Runtime Separation: Platform Proxies