InnoEngine.Rendering2D

A source-based 2D rendering plugin for InnoEngine.

InnoEngine.Rendering2D adds an orthographic 2D rendering model without coupling 2D concepts to the engine's rendering core. The plugin is authored entirely against InnoEngine's public scripting APIs and can run directly from this repository or be exported as a self-contained .iplugin package.

Important

InnoEngine and this plugin are works in progress. APIs and serialized formats may change without backward compatibility. Use matching revisions of both repositories.

Features

• Orthographic and pixel-perfect cameras, layer culling, and deterministic Base/Overlay camera stacks
• Textured, atlas-backed, nine-sliced, tiled, and procedural sprites
• Deterministically composed PNG/TGA sprite atlases and timed animation clips with stable region/event IDs
• Sparse layered tilemaps with dirty chunk revisions, persistent static instance buffers, compact Undo, and tools
• GPU-rasterized global, point, spot, and freeform 2D lights with cookies, four blend styles, layer masks, normal/emission maps, and D24S8 hard/soft shadow volumes
• Sorting groups and D24S8 stencil-backed sprite masks with inside/outside interactions
• HDR intermediate rendering with exposure, contrast, saturation, tone mapping, configurable multi-level Bloom, vignette, and pixelation
• Deterministic CPU particles with fixed-seed simulation and instanced rendering
• Stable sorting layers, shared-quad instancing, frustum culling, and bounded frame generation
• World Canvas content interleaved with sprites through neutral IViewContentSource and the same 2D sorting groups
• Straight alpha, premultiplied alpha, additive, multiply, and opaque material roles
• CPU picking against the same immutable frame used by the Scene viewport
• Scene and Game viewport integration, including pan, cursor-anchored zoom, framing, grid, and axes
• The Scene contributor declares an EditorViewportManipulationPlane.XY contract; the Editor owns native handle presentation, without ImGuizmo types in this Plugin
• Selected Spot Light gizmos follow the rendered local +Y direction, including reflections from negative scale, and show the spot arc and two cone edges instead of a full point-light circle. Point and spot outlines use the same world-unit range as rendering.
• Unified Asset Browser documents for atlases, animations, tile sets, tilemaps, post-processing, and particles
• Named Sprite/clip/layer selectors, isolated Sprite thumbnails, a dockable frame-animation workspace, Atlas move/resize handles, a graphical Tile Palette, and particle curve/gradient editors
• Deterministic MaxRects atlas composition with trim, rotation, extrusion, and named multi-page texture artifacts
• Plugin-owned project settings and native asset importers
• Native Metal, D3D11, D3D12, and Vulkan smoke validation plus a self-hosted GPU CI matrix

Physics, navigation, audio, skeletal animation, SpriteShape, and Aseprite/PSD importing remain separate product lines. The engine's text service and the Canvas plugin own UI fonts, layout, and glyphs; this 2D renderer consumes Canvas world drawables through the neutral view-content contract and does not depend on Canvas or embed font and shaping policy. See the implementation status for the exact completed and pending milestones.

Requirements

• A current checkout or build of InnoEngine
• The .NET SDK 10.0.402 and C# 14 toolchain declared in global.json
• Any platform support packs and native dependencies required by InnoEngine

Start with the 2D authoring guide for the Inspector, Atlas, Sprite Animation panel, Tile Palette, particles, and save/Undo workflows.

Run the development project

The simplest source workflow is to clone the engine and this repository side by side:

GameEngineDev/
├── InnoEngine/
└── InnoEngine.Rendering2D/

From this repository, launch the Inno Editor with the repository root as the project directory:

dotnet run --project ../InnoEngine/entry/InnoEngine.Editor -- .

The editor imports the authored content under Assets/ and regenerates Library/, IDE project files, logs, and other local state. The same launch command accepts a project path with a trailing directory separator.

The pipeline publishes diagnostics through InnoEngine.Diagnostics.Diagnostic and DiagnosticSeverity, using the reporter supplied by RenderPipelineContext. 尚未产生可用 Shader 目标产物时，灯光、阴影和后处理的 NOT_READY 与对应的输出不可用状态为 Warning；编译失败、缺失目标产物或契约/程序失败才报 Error，准备完成后解析临时诊断。Rendering2DModel accepts host RenderOutputSession values and publishes Camera2D output. Scene input comes from the identity-backed content scope; the plugin does not require an engine-owned 2D scene bridge or a native backend API.

GPU validation

Rendering2D 的 .ishadersource 使用 BGFX SC 的跨目标写法；向量常量显式写出所有分量，避免 macOS Metal 可编译但 Windows HLSL 拒绝的单参数 vec3/vec4 构造。Pipeline 在判断各阶段能否绘制前一次性预热当前帧需要的灯光、阴影与后处理材质，使冷启动的 shader 编译可并行推进；产物未准备好时不以降级画面冒充完整输出。安装两份插件包后的 ../TestProject/Tools/Shaders/ShaderCompatibilityProbe.csproj 在 Windows 上逐一编译 D3D11、D3D12、Vulkan、OpenGL 和离线 Metal 的正式 Shader Graph。

On macOS arm64, build the Editor and run the project through a finite Metal smoke session with:

./Tools/Validate-Rendering2D.sh ../InnoEngine 600

On a Windows x64 machine with a physical GPU and the requested driver installed, run one backend at a time:

./Tools/Validate-Rendering2D.ps1 `
  -EngineRoot ../InnoEngine `
  -Backend d3d12 `
  -SmokeFrames 600

Valid Windows backend values are d3d11, d3d12, and vulkan. The scripts build the matching Editor, run the ordinary plugin project for a fixed frame count, reject software renderers and fatal import/backend/ teardown diagnostics, explicitly generate IDE projects through the formal scripts --ide command, and build Editor scripts with warnings as errors. They do not inject a hidden scene, mutate authored assets, or activate production-side acceptance branches. The checked-in GPU workflow uses self-hosted runners carrying the gpu label; a generic hosted VM is not accepted as hardware evidence.

The Windows script accepts -Configuration Debug|Release, -ArtifactsPath, and -TaskArtifactsPath for an explicit SDK output owner. Both the build and TargetPath evaluation use the same selection. For example, keep build outputs on another volume with:

./Tools/Validate-Rendering2D.ps1 -EngineRoot ../InnoEngine -Backend d3d12 `
  -Configuration Release -ArtifactsPath D:/InnoAcceptance/Editor `
  -TaskArtifactsPath D:/InnoAcceptance/Tasks

Use the plugin in a scene

Every scene that opts into 2D rendering must contain exactly one Rendering2DSceneSystem. Add a Camera2D, then add SpriteRenderer2D or TilemapRenderer2D components to scene objects.

using Inno.Rendering2D;
using InnoEngine.Mathematics;
using InnoEngine.Scene;

scene.AddSystem<Rendering2DSceneSystem>();

GameObject cameraObject = scene.CreateObject("Camera");
Camera2D camera = cameraObject.AddComponent<Camera2D>();
camera.pixelPerfect = true;

GameObject spriteObject = scene.CreateObject("Sprite");
SpriteRenderer2D sprite = spriteObject.AddComponent<SpriteRenderer2D>();
sprite.primitive = SpritePrimitive2D.Circle;
sprite.color = new Color(0.2f, 0.65f, 1f, 1f);
sprite.size = new Vector2(2f, 2f);

New Sprite renderers serialize an explicit reference to Materials/DefaultSprite.imaterial. None means no Material and suppresses that renderer with a diagnostic; the Pipeline never silently replaces a missing SpriteRenderer2D.material.

Scenes without Rendering2DSceneSystem are skipped by this plugin, allowing 2D, 3D, and mixed scenes to coexist in the same project. World content from other plugins, including Canvas, enters the same camera view and sorting sequence through IViewContentSource. Rendering2D does not reference those plugins. When more than one render model accepts a host output, configure an exact RenderOutputRoute instead of relying on plugin order.

Package and install

To produce an installable package, open this repository in the Inno Editor and choose File → Export as Plugin.... The package is written to:

Builds/rendering2d.iplugin

Settings.Project.inno explicitly owns the stable Project/Plugin ID rendering2d; it is not inferred again from the checkout directory name. The equivalent headless export uses the same engine build pipeline:

dotnet run --project ../InnoEngine/entry/InnoEngine.Build -- plugin --tools-target windows-x64 --project . --output Builds/rendering2d.iplugin --display-name InnoEngine.Rendering2D

On macOS ARM64, use --tools-target macos-arm64.

Install it in another Inno project by copying the complete package to that project's Plugins/ directory:

MyGame/
├── Assets/
└── Plugins/
    └── rendering2d.iplugin

Installed plugin mounts are read-only. To modify the plugin, edit this authoring project and export a new package. This plugin authoring project leaves its Player startup scene unassigned; consuming projects author their own scenes and select them in Build Settings.

Project layout

Assets/
├── Documentation/   Detailed design and authoring notes
├── Editor/
│   ├── Assets/      Creation, import, inspection, and document integration
│   ├── Authoring/   Sprite-atlas and tilemap authoring algorithms
│   ├── Inspection/ Sprite, component, curve, and gradient drawers
│   ├── Presentation/ Shared plugin fields and isolated previews
│   ├── Settings/    Project settings UI
│   ├── Shaders/     Internal Shader loading, templates, and previews
│   └── Viewports/   Scene and Game viewport contributors
├── Materials/       Default sprite material
├── Pipelines/       Default 2D render pipeline asset
├── Runtime/
│   ├── Assets/      Atlas, animation, tile set, and tilemap asset types
│   ├── Components/  Camera, light, sprite, animator, and tilemap components
│   ├── Pipeline/    Render model and pipeline integration
│   ├── Runtime/     Immutable frame extraction and batching
│   └── Systems/     Per-scene 2D extraction system
├── Shaders/
│   ├── Sprite/      Default Sprite graph, graph-authored nodes, and private sources
│   └── Pipeline/    Lighting, shadows, Bloom, and final-composite programs

For the full feature contract, authoring APIs, camera composition rules, custom materials, and viewport behavior, see the plugin documentation.

Authoring tests

The current authoring UI uses the timeline input API from InnoEngine commit 76ee62807bd164ad1935a6d93e9f00633670867a. The GPU workflow pins this tested revision by default; manual runs may supply an explicit matching Engine revision.

Tools/Test-Authoring.ps1 compiles the current plugin through the formal Build entry, regenerates IDE references, and tests the resulting runtime and Editor assemblies through public contracts. Supply the matching built engine host, an explicit tools target, and an owned output directory:

./Tools/Test-Authoring.ps1 -EngineRoot ../InnoEngine `
  -BuildAssembly <evaluated-InnoEngine.Build.dll> -ToolsTarget windows-x64 `
  -Output <owned-output-directory> -DotNet <dotnet-host>

Use macos-arm64 on Apple Silicon. Both GPU validation scripts also run these tests and write TRX results alongside their logs. The authoring implementation plan and acceptance report distinguish compilation, automated contracts, actual interactions, and platform coverage.

Version-control notes

Assets/ and every .imeta sidecar are authored source and must remain under version control. Settings.Project.inno and Settings.Build.inno, when present, are also project-level source of truth. Generated caches, exported builds, IDE projections, logs, and per-user editor preferences are excluded by .gitignore.

License

This project is available under the MIT License.