Surface Export

Overview

Exports a Surface as a set of PNG textures for a game engine, including albedo, normal, and height. This is the exit for engine-side HD-2D rendering, with selectable naming conventions for Godot/Unity and normal-map Y-axis convention.

• Side effect: yes (has_side_effects: true, writes files)

Usage tips

• Go-to engine settings: Godot StandardMaterial3D → naming=Godot / normal=OpenGL; Unity Lit → naming=Unity / normal=DirectX. See Examples below.
• Follow the standard export-node workflow: use save_mode = Disabled while building, and switch to Overwrite only when exporting.
• CreateIfMissing adds only missing maps to an existing set and warns when that mixes generations. Use CreateSetIfMissing for all-or-none creation of the set.
• Set integer enlargement with scale here when pixel art should display larger in the engine.
• Choose the exit by responsibility: for one fully lit PNG from PixPipeline, use surface_light_preview → batch_export; for engine-side lighting, use this node.

Common pitfalls

• Normals look recessed in the engine: the normal Y-axis convention does not match. Choose OpenGL/DirectX for the engine. Internal storage is OpenGL; G is flipped only for DirectX.
• No files are written: save_mode is still Disabled, as with the other Export nodes.
• Some selected maps are missing: the input Surface has no data for those maps. Check warnings and the internal _omitted_maps result for their stable map IDs.

Technical details

• Internal normal maps use the OpenGL convention (+Y up). Only DirectX output flips G with flip_normal_map_y() from pxn-core.
• Enlargement uses nearest-neighbor interpolation through scale_image_nearest() from pxn-core.
• Enabled maps absent from the input Surface are explicitly omitted; no neutral textures are synthesized. warnings and _omitted_maps: List<Text> report their stable IDs. _written_maps: List<Text> contains only maps actually written by this run, while unchanged / already-exists remain distinguishable through _effect_outcome.

Examples

• Use Image To Surface → Surface Export to create a map set that an HD-2D engine can load as a material.
• For Godot StandardMaterial3D, use naming=Godot / normal=OpenGL. For Unity Lit, use naming=Unity / normal=DirectX.

Related nodes

• solid_render / model_render / image_to_surface — supply the Surface to export
• surface_light_preview + batch_export — alternate route for a lit PNG from the app
• model_gltf_export — import the mesh itself
• tiled_tileset_export — export in tileset format