3D Models

Plinken imports and exports 3D models through a unified Lua API. All formats convert to Plinken’s internal scene graph — load any supported format, modify with Lua, and export to any other.

Import

local scene = pl.scene

-- Load by file extension (auto-detected)
scene:load("character.glb")      -- glTF binary
scene:load("environment.gltf")   -- glTF text + bin
scene:load("furniture.obj")      -- Wavefront OBJ
scene:load("bracket.stl")        -- STL (3D printing)
scene:load("character.fbx")      -- Autodesk FBX
scene:load("model.usdz")         -- Apple USDZ (AR/Vision Pro)
scene:load("scene.usda")         -- USD ASCII
scene:load("saved.p3d")          -- Plinken native (lossless)

scene:load() is additive — each call adds to the existing scene. Load multiple models to compose a scene:

scene:load("stage.glb")
scene:load("singer.fbx")
scene:load("microphone.obj")
scene:load("props.usdz")

Supported Import Formats

Format	Extensions	Materials	Animation	Skeleton	Notes
glTF / GLB	.gltf, .glb	✅ Full PBR	✅	✅	Primary interchange format
FBX	.fbx	✅ Lambert/Phong → PBR	✅	✅	Blender, Maya, Cinema 4D
USDZ / USDA	.usdz, .usda	✅ UsdPreviewSurface	❌	❌	Apple AR / Vision Pro
OBJ	.obj	✅ via .mtl	❌	❌	Widely supported, text-based
STL	.stl	❌ Default gray	❌	❌	3D printing, triangles only
P3D	.p3d	✅ Full	✅	✅	Plinken native — lossless

Planned Import Formats

Format	Extensions	Use Case
IFC	.ifc	Architecture / BIM
DAE	.dae	Collada (legacy)

Export

local scene = pl.scene

-- Load, modify, export
scene:load("raw_scan.obj")

-- Fix up materials
local mat = scene:get_material(0)
mat.base_color = { r = 0.8, g = 0.2, b = 0.1, a = 1.0 }
mat.metallic = 0.0
mat.roughness = 0.7

-- Export
scene:save("final.p3d")          -- Plinken native (lossless)
scene:save("final.usdz")         -- Apple AR / Vision Pro
scene:save("final.glb")          -- Universal interchange (planned)
scene:save("final.obj")          -- Legacy interchange (planned)
scene:save("final.stl")          -- 3D printing (planned)

Supported Export Formats

Format	Extensions	Contents	Notes
P3D	.p3d	Everything — meshes, materials, textures, nodes, animations, skins, properties	Plinken native, lossless round-trip
USDZ	.usdz	Meshes, materials, textures, hierarchy	Apple AR / Vision Pro compatible

Planned Export Formats

Format	Extensions	Notes
GLB	.glb	Universal interchange
OBJ	.obj	Text-based, .mtl sidecar
STL	.stl	3D printing, binary triangles

Native Format: P3D

.p3d is Plinken’s native scene format. It preserves everything — no data loss on save/load.

-- Save complete scene
scene:save("my_scene.p3d")

-- Reload later — everything intact
scene:load("my_scene.p3d")

What P3D preserves that other formats don’t:

• Full scene graph with all node properties
• PBR materials + embedded textures
• Animations + skeletons
• Custom properties (key-value pairs on any node)
• FBX rotation orders and geometric transforms
• USD variant data and composition layers

P3D Binary Format

P3D\0              ← 4-byte magic
u32 version        ← format version
u64 header_len     ← JSON header size
[JSON header]      ← scene graph, materials, animations
u64 binary_len     ← binary data size
[binary chunks]    ← vertex buffers, textures

Format Conversion

Since all formats share the same internal scene graph, Plinken works as a universal 3D converter:

local scene = pl.scene

-- FBX → USDZ (Blender export → Apple AR)
scene:load("character.fbx")
scene:save("character.usdz")

-- OBJ → P3D with custom materials
scene:load("legacy_model.obj")
local mat = scene:get_material(0)
mat.base_color = { r = 0.9, g = 0.9, b = 0.9, a = 1.0 }
mat.metallic = 0.8
mat.roughness = 0.2
scene:save("updated_model.p3d")

-- STL → USDZ for AR preview
scene:load("3d_print.stl")
scene:save("preview.usdz")

FBX Import Details

FBX (Autodesk Filmbox) is the industry standard for 3D content exchange between tools like Blender, Maya, Cinema 4D, and Unreal Engine.

What’s imported:

• Geometry: Polygons triangulated automatically (quads, n-gons → triangles)
• Materials: Lambert/Phong → PBR mapping
• Hierarchy: Full node tree with parent-child relationships
• Transforms: Translation, rotation, scale + FBX-specific pre/post rotation
• Textures: Embedded or file-referenced
• Animations: Translation/rotation/scale keyframes

FBX Material Mapping

FBX Property	PBR Property	Conversion
DiffuseColor	base_color	Direct RGB
SpecularColor	metallic	Luminance as metallic hint
Shininess	roughness	1.0 - (shininess / 100.0)
TransparencyFactor	alpha	1.0 - transparency

FBX-Specific Data (preserved in P3D)

Property	Description
Rotation order	XYZ, XZY, YXZ, YZX, ZXY, ZYX
Pre-rotation	Applied before local rotation (not animatable)
Post-rotation	Applied after local rotation (not animatable)
Geometric transform	Applied to geometry only, not inherited by children

USDZ Import Details

USDZ is Apple’s format for AR content on iOS, iPadOS, and Vision Pro.

What’s imported:

• Meshes: Positions, normals, UVs, face indices (auto-triangulated)
• Materials: UsdPreviewSurface → PBR mapping
• Hierarchy: Xform nodes with transforms
• Lights: DistantLight, SphereLight
• Cameras: Focal length → FOV conversion

USD Material Mapping

USD Property	PBR Property
inputs:diffuseColor	base_color
inputs:metallic	metallic_factor
inputs:roughness	roughness_factor
inputs:opacity	alpha
inputs:emissiveColor	emissive_factor

USDZ Export

Generates Apple-compatible USDZ files:

• USDA text scene description
• Embedded textures (PNG/JPEG)
• Compatible with AR Quick Look, Reality Composer, Vision Pro

OBJ Import Details

OBJ files support:

• Multiple objects/groups → separate scene nodes
• Material library (.mtl) → PBR material mapping
• Texture references (map_Kd) → loaded as base color texture

Material Mapping (MTL → PBR)

MTL Property	PBR Property	Conversion
Kd (diffuse)	base_color	Direct RGB mapping
Ks (specular)	metallic	Luminance as metallic hint
Ns (shininess)	roughness	1.0 - (Ns / 1000.0)
d / Tr (transparency)	alpha	Direct or 1.0 - Tr
map_Kd	Base color texture	Loaded from same directory
map_Bump / bump	Normal map	Loaded from same directory

OBJ without normals

If the OBJ file has no vertex normals (vn), Plinken computes flat normals from face geometry automatically.

STL Import Details

STL is the simplest 3D format — just triangles:

• Each triangle: 3 vertices + 1 face normal
• No UVs, no materials, no hierarchy
• Plinken assigns a default gray material (roughness = 0.5, metallic = 0.0)
• Both ASCII and binary STL are supported

Lossless Data Preservation

Plinken’s internal scene format stores data from all source formats without loss. Even features that can’t be rendered yet are preserved:

Feature	Stored	Rendered	Source Formats
Meshes + materials	✅	✅	All
Animations + skeletons	✅	✅	glTF, FBX, P3D
Curves / NURBS	✅	❌ (future)	USD, FBX
Subdivision surfaces	✅	❌ (polygon fallback)	USD, FBX
Variants / LOD	✅	❌ (default only)	USD
Point instancing	✅	❌ (future)	USD
Volumes (OpenVDB)	✅	❌ (future)	USD
Physics bodies	✅	❌ (future)	USD, FBX
Custom properties	✅	✅ (Lua access)	All
FBX rotation orders	✅	✅	FBX

Save as .p3d to preserve all data for future use.

Workflow Examples

AI-Generated Asset Pipeline

-- Generate an image with AI
local job = pl.create_image({ prompt = "album cover art" })
local result = pl.wait_job(job.jobId)

-- Load a 3D model and apply the AI image as texture
local scene = pl.scene
scene:load("album_case.glb")
local mat = scene:get_material("cover")
mat.base_color_texture = result.url

-- Export for different targets
scene:save("album_with_cover.p3d")     -- native
scene:save("album_with_cover.usdz")    -- Apple AR

Batch Processing

local scene = pl.scene

-- Convert a folder of FBX files to USDZ for AR
local files = pl.list_files("models/", "*.fbx")
for _, file in ipairs(files) do
  scene:clear()
  scene:load(file)
  local out = file:gsub("%.fbx$", ".usdz")
  scene:save(out)
  pl.log("Converted: " .. file .. " → " .. out)
end

Scene Assembly

local scene = pl.scene

-- Build a scene from multiple format sources
scene:load("environment.glb")    -- glTF scene with lighting
scene:load("character.fbx")      -- FBX rigged character
scene:load("furniture.obj")      -- OBJ props
scene:load("ar_overlay.usdz")    -- USDZ AR element

-- Position elements
local character = scene:get_node("character")
character.position = { x = 0, y = 0, z = -2 }

-- Save complete scene
scene:save("composed_scene.p3d")

-- Export for Apple AR
scene:save("composed_scene.usdz")

Compositor Integration

3D scenes render as compositor layers via the plinken-render engine (wgpu):

-- Add a 3D scene to the compositor
pl.cmd("slot:add", {
  name = "3D Scene",
  source = { type = "scene3d", path = "my_scene.p3d" }
})

-- Any supported format works
pl.cmd("slot:add", {
  name = "AR Preview",
  source = { type = "scene3d", path = "model.usdz" }
})

Related

• Nodes — Scene graph hierarchy
• Meshes — Geometry and morph targets
• Materials — PBR properties
• Textures — Image loading
• Animation — Playback and timeline sync