ApprenticeFoundryWorldsAndDrawings 24.0.0

FoundryWorldsAndDrawings

A unified C# / Blazor library that combines 2D Canvas and 3D WebGL visualization capabilities, replacing both FoundryBlazor and BlazorThreeJS with a single, integrated solution.

🎯 Overview

FoundryWorldsAndDrawings is the next-generation unified library that brings together 2D diagramming and 3D visualization in Blazor applications. Built using the Strangler Fig migration pattern, it maintains full backward compatibility while providing enhanced functionality and better architecture.

🔄 Migration from Legacy Libraries

This package replaces:

• ✅ FoundryBlazor (2D Canvas diagramming)
• ✅ BlazorThreeJS (3D WebGL rendering)

Benefits of Migration:

• 🚀 Single Package: One library instead of multiple dependencies
• 🎭 Arena-Scene Bridge: More reliable 3D object management
• 🎬 Enhanced Animations: Better animation system with dirty flagging
• 📁 Unified Static Assets: Standardized asset pipeline
• 🔧 Simplified Setup: Single service registration

✨ Features

2D Capabilities

• Canvas2D Rendering: Complete shape library with advanced drawing capabilities
• Interactive Diagrams: Mouse/touch interactions, pan/zoom, selection
• Glued Connections: Dynamic connections that maintain relationships
• Multi-page Support: Scaled diagrams across multiple pages

3D Capabilities

• WebGL Rendering: High-performance 3D graphics using Three.js
• 3D Model Loading: GLB/GLTF asset support with FoModel3D wrapper
• Animation System: SetAnimationUpdate callbacks with proper dirty flagging
• Transform System: Unified position, rotation, scale with matrix operations
• Camera Controls: Orbit, pan, zoom camera interactions

Unified Features

• Arena Pattern: Reliable 3D object management with Scene bridge
• Cross-platform: Works in both Blazor Server and WebAssembly
• Performance Optimized: Object pooling, dirty flagging, efficient rendering
• TypeScript Integration: Seamless JavaScript interop

📦 Installation

dotnet add package FoundryWorldsAndDrawings

🚀 Quick Start

1. Service Registration

// Program.cs - Single registration replaces multiple libraries
using FoundryWorldsAndDrawings;

var builder = WebApplication.CreateBuilder(args);

// Add unified services (replaces AddFoundryBlazorServices + AddBlazorThreeJSServices)
var envConfig = new EnvConfig("./.env");
builder.Services.AddFoundryWorldsAndDrawingsServices(envConfig);

var app = builder.Build();

// Enable static file serving for 3D models
app.UseStaticFiles();

2. Basic 3D Component

@page "/my3d"
@using FoundryWorldsAndDrawings.ThreeD.Viewers
@using FoundryWorldsAndDrawings.Shared
@using FoundryWorldsAndDrawings.Solutions
@rendermode InteractiveServer

<h3>My 3D Scene</h3>

<div class="d-flex">
    <Canvas3DComponent SceneName="MyScene" @ref="Canvas3DReference" CanvasWidth="1200" CanvasHeight="800" />
    <div class="controls">
        <button class="btn btn-primary" @onclick="AddModel">Add 3D Model</button>
        <button class="btn btn-success" @onclick="StartAnimation">Start Animation</button>
    </div>
</div>

@code {
    [Inject] public IWorkspace Workspace { get; set; } = null!;
    [Inject] public NavigationManager Navigation { get; set; } = null!;
    
    public Canvas3DComponent Canvas3DReference = null!;
    
    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            // Establish Arena-Scene bridge
            var (found, scene) = Canvas3DReference?.GetActiveScene() ?? (false, null!);
            var arena = Workspace.GetArena();
            if (found) arena.SetScene(scene!);
        }
    }
    
    public void AddModel()
    {
        // Arena pattern - recommended approach
        var shape = new FoModel3D("MyModel")
        {
            Url = GetReferenceTo(@"storage/StaticFiles/model.glb"),
            Transform = new Transform3("ModelTransform")
            {
                Position = new Vector3(0, 0, 0),
                Scale = new Vector3(1, 1, 1),
            }
        };
        
        var arena = Workspace.GetArena();
        arena.AddShapeToStage<FoModel3D>(shape);
    }
    
    public void StartAnimation()
    {
        // Add animation to existing objects
        var arena = Workspace.GetArena();
        var shapes = arena.GetShapes<FoModel3D>();
        
        foreach (var shape in shapes)
        {
            shape.SetAnimationUpdate((self, tick, fps) =>
            {
                // Rotate around Y axis
                self.Transform.RotateBy(0, 0.01, 0, AngleUnit.Radians);
                self.SetDirty(self.Transform.IsDirty);
            });
        }
    }
    
    public string GetReferenceTo(string filename)
    {
        return Path.Combine(Navigation.BaseUri, filename);
    }
}

3. Static Asset Setup

# Place 3D models in:
wwwroot/storage/StaticFiles/
├── model.glb
├── texture.jpg
└── other-assets.*

📚 Documentation

Migration Guides

• Migration Guide - Complete step-by-step migration from legacy libraries
• Architecture Guide - Technical architecture and design patterns
• Quick Reference - Fast migration reference and common patterns

Technical Documentation

• Matrix3D Compatibility - Matrix mathematics and compatibility layer
• Arena Pattern - Reliable 3D object management
• Transform System - Position, rotation, scale operations

🏗️ Architecture Highlights

Arena-Scene Bridge Pattern

// High-level object management (Arena)
var arena = Workspace.GetArena();
arena.AddShapeToStage<FoModel3D>(shape);

// Low-level rendering (Scene) - automatically bridged
var (found, scene) = arena.CurrentScene();
// Arena manages Scene connection

Unified Service Architecture

// Single service provides everything
[Inject] public IFoundryService FoundryService { get; set; } = null!;
[Inject] public IWorkspace Workspace { get; set; } = null!;

// Access sub-services
var arena = Workspace.GetArena();      // 3D object management
var drawing = Workspace.GetDrawing();  // 2D canvas management

Enhanced Animation System

shape.SetAnimationUpdate((self, tick, fps) =>
{
    // Any animation logic
    var pos = self.Transform.MoveBy(deltaX, deltaY, deltaZ);
    self.Transform.RotateBy(0, rotationSpeed, 0, AngleUnit.Radians);
    
    // Trigger re-render
    self.SetDirty(self.Transform.IsDirty);
});

🔄 Migration from Legacy Libraries

Before (Multiple Libraries)

// OLD - Multiple packages and registrations
builder.Services.AddFoundryBlazorServices(envConfig);
builder.Services.AddBlazorThreeJSServices(envConfig);

[Inject] public IFoundryBlazorService Foundry { get; set; }
[Inject] public IBlazorThreeJSService ThreeJS { get; set; }

After (Unified Library)

// NEW - Single package and registration
builder.Services.AddFoundryWorldsAndDrawingsServices(envConfig);

[Inject] public IFoundryService FoundryService { get; set; }
[Inject] public IWorkspace Workspace { get; set; }

✅ Zero Breaking Changes - All existing functionality preserved!

🎮 Interactive Demo

Explore the complete reference implementation:

• CanvasRebirth Project - Full working examples with multiple pages
• Clock Page - Real-time animations with Arena pattern
• SpacialFrameTest - 3D geometry visualization and transforms
• Home Page - Basic 3D model loading and rendering

📋 Requirements

• .NET 8 or higher
• Blazor Server or WebAssembly
• Modern Browser with WebGL support

🛠️ Troubleshooting

Models Not Loading

• ✅ Add app.UseStaticFiles() to Program.cs
• ✅ Place models in /wwwroot/storage/StaticFiles/
• ✅ Use GetReferenceTo(@"storage/StaticFiles/model.glb")

Animations Not Working

• ✅ Use Arena pattern: arena.AddShapeToStage<FoModel3D>(shape)
• ✅ Call SetDirty() in animation callbacks
• ✅ Establish Arena-Scene bridge in OnAfterRenderAsync

Service Injection Errors

• ✅ Update to unified registration: AddFoundryWorldsAndDrawingsServices()
• ✅ Update service interfaces: IFoundryService, IWorkspace
• ✅ Update using statements to FoundryWorldsAndDrawings.*

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.

💬 Support

• 📖 Documentation: See migration guides and architecture documentation
• 🐛 Issues: Submit issues on GitHub for bug reports and feature requests
• 💡 Examples: Reference the CanvasRebirth project for working implementations
• 🚀 Migration Help: Use the provided migration guide for upgrading from legacy libraries

Ready to build amazing 2D/3D Blazor applications with FoundryWorldsAndDrawings! 🎉