Referencing Assets

In a Voxel Scene, you can use other assets through Reference objects.

A Reference object generates voxel data from the assigned asset and uses that result inside the scene.

Creating a Reference

You can create a Reference by dragging an asset into the scene or by creating a Reference object manually.

Drag and Drop

1. Switch to the Assets page.
2. In the right panel, locate the asset you want to reference.
3. Drag the asset into the Scene View.
4. Release the mouse at the position where you want to place the Reference.

Foxel creates a matching Reference object automatically, assigns the asset, and loads the generated voxel data.

The Reference is placed at the drop position. If you drop the asset on the ground, the Reference is placed on the ground. If you drop it onto a voxel surface, the Reference is placed at that surface.

Drag and Drop Modifiers

You can hold modifier keys while dropping an asset to control how the Reference is placed.

Modifier	Result
No modifier	Creates a Reference at the drop position.
Shift	Aligns the Reference to the hovered face.
Ctrl	Parents the Reference to the hovered object while keeping its visible placement.
Shift+Ctrl	Aligns the Reference to the hovered face and parents it to the hovered object.

Use Shift when you want the Reference to follow the direction of a wall, ceiling, side face, or other voxel surface.

Use Ctrl when the Reference should become part of another object’s hierarchy. This is useful when the referenced asset should move, rotate, or animate together with the hovered object.

Add as Reference to Scene

You can also add an asset as a Reference from the asset context menu:

1. Switch to the Assets page.
2. Right-click the asset you want to reference.
3. Choose Add as Reference to Scene.

This creates a Reference object for the selected asset and adds it to the current scene.

Unlike drag and drop, this command does not let you choose the placement position interactively.

Create a Reference Manually

1. Choose Object > Create and create the appropriate Reference object type.
2. Select the new Reference object.
3. In the Inspector, set the Asset property to the asset you want to reference.

Make sure the Reference type matches the assigned asset type.

Updating References

References are not updated automatically. If the source asset changes, existing Reference objects will continue to use their previous generated data until they are updated.

To refresh references, use:

• Object > References > Update to update the selected references
• Object > References > Update All to update all references in the scene

Converting References

The voxel data generated by a Reference object cannot be edited directly as individual voxels.

To make the result editable, convert the Reference to a Voxel Layer:

• Object > Reference > Convert to Voxel Layer

This creates a voxel layer from the currently generated result.

Breaking References

You can also break a reference. This removes the link to the source asset and inserts converted content into the scene hierarchy.

To do this, use:

• Object > Reference > Break

The result depends on the referenced asset type:

• Voxel Scene: Copies the Voxel Objects into the hierarchy. Nested references are converted to Voxel Layers.
• Mesh Asset: Voxelizes the mesh data and adds the result to the hierarchy.
• Voxel Movie: Copies the frames and adds visibility keyframes so the animation is preserved.
• Heightmap: Creates a copy of the generated voxel data.

How Voxel Data Is Generated

The way voxel data is generated depends on the type of asset being referenced.

Voxel Scene and Mesh Asset

For Voxel Scenes and Mesh Assets, Foxel uses voxelization.

1. Scan Box: The selected Scan Box defines which region of the source asset is used.
2. Voxelization: Foxel voxelizes the content inside that region.
3. Merged Result: The generated voxel data is combined into a single voxel result for the Reference object.

The Scan Box used by a Reference can be selected in the Inspector. You can use either:

• the asset’s Default Scan Box
• a custom Scan Box object inside the referenced asset

Heightmap

For Heightmaps, Foxel converts the 2D image-based data into voxel data using the stored height information.

Voxel Movie

For Voxel Movies, the Reference object uses the voxel data of the selected frame.