星火 2.0 开发文档

主题

GameGraph 2D Rendering ​

Read 二维渲染路径与颜色指南 before implementing a flat sprite viewport or diagnosing its colors. In a generated project, the guide is at docs/sdk/guides/GameGraph2DRendering.md; this skill's XML assets stay under assets/RenderPaths/.

Choose The Output Contract ​

  • A dedicated unlit 2D main view can use the supplied Flat2DLinear.xml and Flat2DBackbuffer.xml. Copy them into project res/RenderPaths/; code uses RenderPaths/... without res/. They draw the default sprites' alpha pass only.
  • assets/Flat2DMainView.cs is a reusable main-view owner. Copy it into project source and keep it alive through gameplay; the owner explicitly disposes it before the graph on level/game end and initialization failure.
  • A 2D sprite embedded in a lit 3D scene should usually keep that scene's intended path. Do not replace the whole scene with the flat path: opaque meshes, lighting and other passes would disappear.
  • Canvas/GameUI, transparent overlays and custom RenderToTexture targets have separate output contracts. For an RTT, determine its texture format/sRGB flag and downstream consumer before choosing Gamma encoding. The main editor-canvas property alone does not classify an arbitrary RTT.

Implementation Invariants ​

  • SceneGraphMainViewportController.Bind / Renderer.SetupMainViewport retain the host RenderPath. An independent SceneGraph and an orthographic camera do not isolate fullscreen effects. Set the dedicated view's path explicitly during initialization.
  • Default Urho2D sprites are unlit, but fullscreen Bloom/tone mapping, saturation, multiply and vignette can still alter them. The engine's BloomHDR combine includes ACES filmic tone mapping; zero glow strength does not establish a color-neutral output.
  • For ordinary PNG color art, configure the matching texture XML with srgb=true and preserve intentional existing resource settings. Composite in linear space and perform final Gamma encoding once. Treat data/mask/normal textures separately.
  • Renderer.IsEditorDebugViewportActive distinguishes the main PIE canvas from a standalone backbuffer. PIE receives linear output and its editor UI encodes it; the standalone path uses GammaCorrection with an explicit rgba16f linear buffer. Do not select by Game.IsClientOnly or apply Gamma twice.
  • Keep the existing normal-game postprocessing setting enabled for this baseline. Disabling the global postprocessing switch can change sprite shader defines and encoding; do not use it as a shortcut to remove Bloom.
  • Save the retained Viewport.GetRenderPath() reference and every viewport option you change. Restore them before disposing the viewport controller and graph, then dispose the retained path wrapper. Own cleanup on initialization failure, level changes and game end.
  • A dedicated default-unlit sprite scene needs no LightGroup just to restore its original colors. Inspect LightGroup/Zone when the selected path uses their postprocessing parameters; do not reset global lighting as an unexplained workaround.

Verify The Result ​

Use the existing project's normal editor debug workflow for iteration. Include an independent-client comparison when diagnosing that route; follow the project's debug tools and process ownership rules.

  • Record the chosen RenderPath, actual editor-canvas state and current resources. Check SetRenderPath's return value.
  • Compare cold PIE, PIE after a 3D run, and standalone output against the same source PNG and sprite tint. Window aspect ratio changes framing, not the intended palette.
  • Inspect runtime screenshots and game rendering logs. GammaCorrection() and GammaCorrection(GAMMA_IN_SHADERING) are distinct requested variants; published shaders must cover the actual platform and define string. A successful XML load or C# build does not prove shader availability.
  • A black map with a visible HUD warrants checking shader failures as well as scene/camera visibility. Do not compensate for missing shaders by changing texture sRGB flags.
  • Report platform limits: the supplied path's Windows main-view colors have been tested; mobile GPU/format behavior, custom materials and diagnostic postprocessing-disabled modes need their own checks.