io.import (procNode)

Take a scene concept, the entities and components of zero space, or the value an asset states, and turn it into procgen values: the Geometry, elements and piece sets a graph works on. source is an asset, and value is what the node makes of it.

The node makes a value of an asset by the first of these its type offers:

1. A graph conversion its behavior states. The type states one of:
   • import: it answers the record it reads, and the members it names in columns are put on the device. A texture is { width, height, format, texels }, its texels one { x, y, z, w } each; a landscape (.terrainData) is its ground, { cols, rows, minX, minZ, sizeX, sizeZ, heights };
   • record, the record kind its assets load as: it answers one element holding the record its kind loads, the way a node that makes such a record answers. A .material is one element whose Material attribute holds the material record, with the kind on the detail attribute records;
   • read: it answers that value. A mesh is a Geometry; a population is the copies it places, the form instances.to_points answers; a .procRecord is the record kind itself ({ kind, name, asset, applies }); a bundle and a scene are their entities as elements.
2. instantiate. A type that states no graph conversion and defines instantiate (ref:canInstantiate()) is instantiated, and the entities the instantiation produces are answered as elements. The node instantiates the asset under a temporary root, which is internal, hidden and inactive, reads the entities beneath it, and despawns the root and everything under it before the node answers, including when reading raises.

The asset is read when the node cooks, and an edit to it cooks the node again.

Elements

The entities of a bundle, a scene or an instantiated asset answer as one point per entity, numbered from 0, carrying name, parent (the number of the entity it hangs under, -1 for none), P, orient and scale (the entity's own pose), and one attribute per script component, named after the component's type as the record states it (@builtin::components.Light) and holding the component's data.

• A bundle and a scene list their entities in the order the asset holds them. An instantiated asset lists its root first, then each entity's children after it in name order, a parent always before its children.
• An entity drawn through the native Mesh and Material components carries them as Mesh and Material records. An instantiated entity's native components are read from the live entity, a field holding an asset written as the asset's guid.
• An entity drawn through a Model component carries Mesh (the mesh asset, with the Model's shadow settings) and Material, and no Model attribute.
• A Model field that dresses the draw (tint, outline, light channels, mobility) set away from a fresh Model's, and a hidden Model (whose element then carries no Mesh), are listed in the detail attribute reported, as is any other native component.
• A SkinnedModel stays an attribute of its own.
• instances.from_elements turns the elements into a piece set that instances.to_points places.

This is the form io.output stands and io.export saves. To place a mesh on points with instances.to_points, import the mesh asset itself (a mesh asset answers a Geometry) and pack it with instances.pack.

local lamp = g.io.import({ source = asset.resolve("@builtin::bundles.lamp_post", "bundle") })
local pieces = g.instances.from_elements({ elements = lamp }).pieces

An asset with neither

An asset whose type states no graph conversion and defines no instantiate is refused: the error says the type states no graph conversion and cannot be instantiated.

local rock = g.io.import({ source = asset.resolve("@builtin::meshes.cube", "mesh") })
local lamp = g.io.import({ source = asset.resolve("@builtin::bundles.lamp_post", "bundle") })
local ground = g.io.import({ source = landscape, options = { cols = 65, rows = 65 } })

Inputs

• source (AssetRef). The asset brought in, written asset.resolve("<identity>", "<type>").
• options (Record, optional). What the asset's type reads it with: a landscape's cols and rows, the samples its heights are read at along x and z (129 each when left out). A type that reads nothing takes none.

Outputs

• value: the asset as the value the node makes of it.