Craft

Craft provides extended capabilities to Codea that make it much easier to create 3D scenes, physics and game logic. Craft introduces a number of new classes. These include craft.entity, which is the basic building block of 3D scenes.

Several systems are introduced, including: craft.scene - The core class in craft, draws and updates all other objects and systems craft.physics - Physics settings and helper functions craft.voxels - Streaming voxel terrain, block types and helper functions craft.ar - Augmented Reality, world tracking and helper functions

Each system can be used to access built-in objects, change settings or trigger specialised features.

In order to use craft you must make a scene. Scenes are used to create, update and draw all entities and components. Scenes also control basic things, such as ambient lighting, fog, the sky and contain references to some built-in entities.

Built-in entities include: a main camera that renders the scene by default a 'sun' which is a directional light a 'sky' which is a renderer with a Materials:Skybox material used to draw the background

Entities are flexible objects that can be customised to change their appearance and behaviour. You can customise an entity by adding components. Each type of component serves a different purpose. Renderer components change entity appearance, physics components give entities physical behaviour.

Adds a component to this entity. There are several built-in components that can be added, such as craft.renderer, craft.shape.box and others. Lua classes can also be added as a component. Any additional parameters beyond the type will be forwarded to the component itself. For Lua classes the first parameter passed to the init() function will be the entity itself (followed by the rest of the arguments) allowing it to be stored for later use. Some special callback methods can be implemented in Lua classes to provide extra functionality.

The update() method will be called once per frame (useful for animations and game logic). The fixedUpdate() method will be called once per physics update (useful for physics related behaviour).

If the component is successfully added, the component will be returned. Only one of a given component type can be added at a time.

Gets a component of a particular type attached to this entity. If the component does not exist, nil is returned.

Removes a component of a particular type attached to this entity, if it exists.

Marks this entity for destruction in the next frame. Any children will also be marked for destruction.

Transforms a point from local space into world space using this entity's transform.

Transforms a point from world space into local space using this entity's transform.

Transforms a direction from local space into world space using this entity's transform.

Transforms a direction from world space into local space using this entity's transform.

A component used to draw the scene from its point of view.

Converts a position given in screen coordinates (x, y) and a depth value (z) to world space relative to this camera.

Converts a position in screen coordinates (x, y) to a ray in the form of an origin and direction relative to this camera.

Converts a position given in world coordinates to screen coordinates relative to this camera.

Sets or gets the current viewport using normalized coordinates. Can be used for adjusting the rendered area of the camera relative to the screen. For instance, calling camera:viewport(0.0, 0.0, 0.5, 1.0) will render the camera to only the left half of the screen.

A component used to draw a 3D model in the scene. Renderers can be attached to entities by using entity:add(craft.renderer) or by setting entity.model and entity.material directly.

A component that casts light onto the scene. Different types of lights can be used to achieve different lighting effects, these include: DIRECTIONAL, SPOT and POINT. The position and rotation of the entity controls the position and rotation of the attached light source. By default the scene contains a single directional light known as the sun.

The scene also contains an ambient light controlled by scene.ambientColor. The ambient light term is added to the emission of all other lights and is generally used for simulating scattered environmental light.

This constant specifies the directional light type. Directional lights simulate an infinitely distant light source where all rays are parallel (similar to the sun). The position of a directional light is ignored.

This constant specifies the spot light type. Spotlights simulate a cone of light within a specified angle (see the angle property). The distance and decay properties define how far the light travels and how quickly the intensity falls off over distance.

The penumbra property defines how hard the edge of the spotlight is. The closer this value is to angle the harder the edge will appear. Setting this to zero will give the appearance of very soft spotlight.

This constant specifies the point light type. Point lights simulate a omnidirectional light source emitting from a single point. The distance and decay properties define how far the light travels and how quickly the intensity falls off over distance.

This type represents a surface material. Materials are used to control the physical appearance of 3D objects, such as models, sky boxes and voxels.

Set the material property on a craft.renderer component to apply a given material to it. Materials are built out of modular shaders with a set of dynamic properties.

Each named property has a different effect on the material's appearance. For instance, the map property can be set with an image or asset string to change the surface appearance of the Standard material. Other properties can change the normals, roughness, metalness and reflectiveness of materials.

This type represents a model. Used in conjunction with a craft.renderer component to draw 3D objects.

Existing model assets can be loaded by using craft.model(asset), supported 3D model formats are .obj, .fbx, .stl and .blend.

Models are made up of a number of triangles, which are in-turn made up of vertices. Each vertex has a number of attributes that control their appearance, such as position, color and normal.

To make a triangle you must set the indices of the model using the indices property. You can resize the number of indices and vertices by using the resizeIndices() and resizeVertices() functions.

Creates a cube model with the specified size and offset. By default the size parameter is set to (1,1,1), and the offset parameter is (0,0,0).

Creates an icosphere model. An icosphere is a geodesic dome made from equally sized triangles. The number of subdivisions specified will control how dense the sphere is (increasing the number of triangles). Setting the icosphere to flat will created faceted faces, otherwise the icosphere will have a smooth appearance.

Creates a horizontal plane model with the specified size and offset. By default the size parameter is set to (1, 1), and the offset parameter is (0, 0, 0).

Sets the number of vertices in the model.

Sets the number of indices in the model where each set of 3 indices forms a triangle.

Set or get the position for a vertex within this model.

Use with only the index parameter to return the x, y, z values of a vertex position (as 3 separate values).

Set or get the normal for a vertex within this model.

Use with only the index parameter to return the x, y, z values of a vertex normal (as 3 separate values).

Set or get the color for a vertex within this model.

Use with only the index parameter to return the r, g, b, a values of a vertex color (as 4 separate values).

Set or get the uv for a vertex within this model.

Use with only the index parameter to return the u, v values of a vertex uv (as 2 separate values).

This returns the number of submeshes available in the model. It can be used to find the range of indices needed for the getMaterial and setMaterial methods

Note that submeshes are indexed from 1 to submeshCount

Get the material for a submesh within this model. You can use the submeshCount property of the model to get the number of submeshes with distinct materials

Note that submeshes are indexed from 1 to submeshCount. If an index is not provided it defaults to 1

Set the material for a submesh within this model. You can use the submeshCount property of the model to get the number of submeshes with distinct materials

Note that submeshes are indexed from 1 to submeshCount. If an index is not provided it defaults to 1

Adds a variable number of indices to the model. Each index must be within the range 1..model.vertexCount

Clears all buffers in all submeshes associated with this model. Effectively removing all its geometry

This is useful for re-using a model object multiple times

This function modifies the model geometry to ensure that each triangle has unique vertices. So that no triangle shares vertex indexes with its neighbours. Calling this will increase the number of vertices in the model (if it is not already split)

The index parameter (defaults to 1) allows you to specify which submesh is split. If a model has multiple submeshes you will need to call split multiple times, one for each submesh up to submeshCount

The system governing all 3D physics in a scene.

Performs a raycast in the scene against any rigidbodies with attached shapes.

Performs a spherecast in the scene against any rigidbodies with attached shapes. A spherecast works by projecting a sphere in the direction of the cast and detecting any shapes that it intersects.

This type represents a 3D rigidbody. Attach this to an entity to make it respond to forces and collisions. When creating a rigidbody you must specify the type you want to create. Refer to the documentation for DYNAMIC, STATIC and KINEMATIC for more details.

This constant specifies the dynamic body type. Dynamic bodies move under the influence of collisions, forces, joints and gravity.

This constant specifies the static body type. Static bodies are unaffected by forces and collisions. They also do not collide with other static or kinematic bodies.Also note that you cannot attach two static/kinematic bodies together with a joint.

This constant specifies the kinematic body type. Kinematic bodies are unaffected by forces and collisions. Unlike static bodies, kinematic bodies are meant to be moved, usually by setting linear velocity directly. They also do not collide with other static or kinematic bodies. Also note that you cannot attach two static/kinematic bodies together with a joint.

Applies a force to this rigidbody. If worldPoint is not specified then the force will be applied to the center of the rigidbody.

Applies torque to this rigidbody.

This component represents a box physics shape. Attach this to an entity with a rigidbody to make it respond to physical forces.

This component represents a sphere physics shape. Attach this to an entity with a rigidbody to make it respond to physical forces.

This component represents an arbitrary physics shape made from a model. Attach this to an entity with a rigidbody to make it respond to physical forces.

This component represents a capsule physics shape. Attach this to an entity with a rigidbody to make it respond to physical forces.

The voxel system, used to manage streaming voxel terrain. Initially no voxels exist as the terrain is completely empty. Using voxels:resize() will create an empty patch of terrain, consisting of empty blocks. Once some terrain has been allocated voxels:generate() can be used to generate the landscape one chunk at a time via a multi-threaded generation system. See the Voxel Terrain project for an example of how this works. Using voxels:enableStorage(storage) allows voxels to be saved to a project subfolder with the specified name. As a technical note, volumes and chunks are saved as zlib compressed json files. Block types, scheduled updates and block entities are all saved. If a block id changes due to inserting a new block type of removing an existing one, the loaded chunk/volume may change unexpectedly.

Resizes the voxel terrain to a specified size divided into chunks, which can be generated and streamed efficiently.

Triggers voxel terrain generation using lua code provided as a string and the number of a function to call. The specified function must exist within generationCode and must take a single parameter which is the chunk that will be generated. See craft.volume for available methods for manipulating chunks.

Gets data from a block at a particular location using the specified key(s). There are a number that can be used for different block data:

BLOCK_ID - Get this block's id (int) BLOCK_NAME - Get this block's name (string) BLOCK_STATE - Get this block's state (int) COLOR - Get this block's tint color (color), only works for tinted blocks To get custom block properties, use a string with the name of that property. When called with no keys specified a block instance will be returned which has methods which can be called directly.

Sets data on a block at a particular location for the specified key(s). There are several that can be used for different block data:

BLOCK_ID - Set this blocks id (int), effectively changing the type of block BLOCK_NAME - Set this blocks name (string), effectively changing the type of block BLOCK_STATE - Set this blocks state (int) COLOR - Set this blocks tint color (color), only works for tinted blocks

If a block changes its own type then it will behave as the new block and will trigger any destroyed() and created() callbacks.

To modify custom block properties, use a string with the name of that property.

Sets the current fill block. Takes the same parameters as voxels.set. This is used for basic drawing operations such as sphere, box and line.

Sets the current fill style. There are several styles that can be used:

REPLACE - Replace fill style, new blocks will replace any existing ones UNION - Union fill style, new blocks will only replace empty ones UNTERSECT - Intersect style, new blocks will only replace non-existing ones CLEAR - Clear style, new blocks will clear any existing blocks

Sets a single block using the current fill() and fillStyle() settings.

Sets a sphere shaped array of blocks using the coord and radius

Sets a box shaped array of blocks using the minimum and maximum coordinates supplied.

Sets a line shaped array of blocks using the minimum and maximum coordinates supplied.

Schedules a block update for the block at a specified coordinate. The ticks parameter controls how long in the future before the update will occur. Each tick is roughly 1/60th of a second. Using 0 will cause an update to occur next frame.

Block updates call the blockUpdate(ticks) method on scripted blocks. Block updates can be triggered inside a scripted block itself by using self:schedule(ticks).

Performs a raycast on the voxel terrain. The callback provided must follow the signature:

function callback(coord, id, face)

The coord parameter (vec3) contains the coordinate of the current voxel encountered.

If coord is nil, this means the raycast has gone outside of the bounds of the voxel terrain (i.e. no voxel found).

The id parameter contains the id of the current voxel encountered.

The face parameter (vec3) contains the direction of the face hit by the raycast (i.e. vec3(0,1,0) would be the top).

At each step the callback function can return true or false. Returning true will terminate the raycast early, false will continue the raycast until the maximum distance is reached.

Iterates through all blocks within the min and max bounds provided sending the information to a callback function. The callback function should take the following form function myCallback(x, y, z, id).

Checks if all the voxels within the min and max bounds are currently loaded. This is useful for generating more complex structures that make require adjacent areas to be loaded.

Enables storage within the voxel system. This causes regions to be saved within the project inside a folder named storageName.

Disables storage.

Deletes a particular storage folder (if it exists).

This type represents a specific voxel block variant. You can create a block type via scene.voxels.blocks:new( name ).

By default a block type has the appearance of a white cube (1x1x1 units). A block type's appearance can be customised by adding and removing cubes of various sizes, changing their textures or applying tints.

A block type's behaviour can be customised by enabling scriping and adding special methods to it:

blockType:created() - called when the block is created blockType:destroyed() - called when the block is destroyed (removed) blockType:buildModel(model) - called when the block is about to be modeled

Instances of scripted blocks cannot store additional data in their tables unless they are set to dynamic. Non-dynamic blocks have up to 32 bits of state that can be used to store per-block data (see block.state for more information). Dynamic blocks can store additional values in their tables. Dynamic blocks come with their own entity, which can be used to render custom models, or animate them in ways static blocks cannot.

Scripted and dynamic blocks use significantly more resources than standard non-scripted blocks and care must be taken to avoid using too much memory or slowing down the voxel system. A good rule of thumb is to match the complexity of a custom block to how often it is used.

Please note that any properties marked instance only can only be accessed via block instances, i.e. those created by setting voxels and passed into callbacks.

Gets data from this block for the specified key. There are a number of that can be used for different block data.

BLOCK_ID - Get this block's id (int) BLOCK_NAME - Get this block's name (string) BLOCK_STATE - Get this block's state (int) COLOR - Get this block's tint color (color), only works for tinted blocks To get custom block properties, use a string with the name of that property.

Sets data on this block for the specified key. There are a number of that can be used for different block data.

BLOCK_ID - Set this blocks id (int), effectively changing the type of block BLOCK_NAME - Set this blocks name (string), effectively changing the type of block BLOCK_STATE - Set this blocks state (int) COLOR - Set this blocks tint color (color), only works for tinted blocks

If a block changes its own type then it will behave as the new block and will trigger any destroyed() and created() callbacks.

To modify custom block properties, use a string with the name of that property.

This component represents a 3D voxel volume. Voxel volume components store block data as well as handling rendering and physics.

Returns the size of this volume in voxels as 3 components (x, y, z).

Gets data from a block at a particular location using the specified key(s). There are a number that can be used for different block data:

BLOCK_ID - Get this block's id (int) BLOCK_NAME - Get this block's name (string) BLOCK_STATE - Get this block's state (int) COLOR - Get this block's tint color (color), only works for tinted blocks To get custom block properties, use a string with the name of that property.

Sets a block within this volume at the coordinates given (x, y, z). Coordinates can be supplied as either a vec3, or as a set of 3 numbers.

Resizes the volume to a specific size.

Loads a saved volume.

Saves a volume as a voxel asset.

The Augmented Reality (AR) system. Please note that to use the AR feature your device must possess an A9 or greater processor. To determine if your device supports AR, use craft.ar.isSupported.

Only some devices support AR face tracking - these include devices with a TrueDepth camera, such as the iPhone X product line (X, XR, XS, XS Max) and iPad Pro 2018 and above models. To determine if your device supports AR face tracking, use craft.ar.isFaceTrackingSupported.

To enable AR, use scene.ar:run(). This will use the sky to render the camera feed to the background. If you do not want to display the camera feed, simply disable the sky. To disable AR you can call the pause() function.

To enable AR face tracking supply an addition parameter in the form of scene.ar:run(AR_FACE_TRACKING).

In world tracking configuration the AR system will automatically try to detect and estimate horizontal and vertical planes in the scene. To be notified of when this happens you must set the anchor callbacks, such as scene.ar.didAddAnchors. These will be called with an array of anchor objects which contain a position and extent which can be used for positioning objects in the world.

To interact with the AR world, use hitTest(screenPoint, options), and check the array of hitTestResult objects for any intersections.

Enables AR if possible. This overrides the sky's visuals as well as the main camera's transform and projection matrix.

Pauses AR.

Performs a hit test (raycast) against the AR world. Any objects that are hit by the ray are returned as a list of craft.ar.hitTestResult.

The options parameter is a bitmask with the following flags: AR_FEATURE_POINT - Search for feature points AR_ESTIMATED_PLANE - Search for estimated horizontal surfaces AR_EXISTING_PLANE - Search for detected planes AR_EXISTING_PLANE_CLIPPED - Search for detected planes (clipped to edges)

Generates an AR face model from the supplied blend shape table. This table is in the same format as the one supplied by the face anchor blendShapes property.

An anchor in the AR world. These can represent a point (single location) or a plane (flat surface). The identifier property is useful for uniquely identifying anchors that are automatically created by plane detection.

When running an AR face tracking session, the anchor will contain additional data, such as blendShapes and faceModel.

The blendShapes property returns a table of facial expression data, where each key is a string relating to the expression and the corresponding value is a number between 0 and 1. There are a very large number of keys and so you may find it useful to use the AR Face example project to browse though them.

A hit test result that is returned by the ar:hitTest() function. The type of hittest can be

This constant specifies the AR world tracking session type used in the ar.run() method.

This constant specifies the AR face tracking session type used in the ar.run() method.

This constant specifies that AR world tracking is not currently available. Returned by ar.trackingState.

This constant specifies that AR world tracking is currently limited. Returned by ar.trackingState, with further details returned by ar.trackingStateReason.

This constant specifies that AR world tracking is currently normal. Returned by ar.trackingState.

This constant specifies that AR world tracking is not currently limited. Returned by ar.trackingStateReason.

This constant specifies that AR world tracking is currently limited due to excessive device motion. Returned by ar.trackingStateReason.

This constant specifies that AR world tracking is currently limited due to insufficient feature points. This could be due to a lack of contrasting features on surfaces (such as a white table or mirrored surface). Returned by ar.trackingStateReason.

Used by ar:hitTest as a mask for detecting feature points during hit test.

Used by ar:hitTest as a mask for detecting estimated planes during hit test.

Used by ar:hitTest as a mask for detecting existing planes during hit test.

Used by ar:hitTest as a mask for detecting existing planes (clipped to edges) during hit test.

The noise library contains a series of noise modules that can be used to generate a large variety of procedural content. Use getValue(x,y,z) to generate a scalar noise value. Some modules take a number of inputs (set with setSource(input)).

Noise modules fall into the following catagories: Generators - These modules generate values directly and require no inputs Transformers - These modules transform their inputs in some way to create a new effect

Refer to each individual module's documentation to see how they work.

A perlin noise generator module. Zero inputs.

A rigid multi-fractal noise generator module. Zero inputs.

A billow noise generator module. Zero inputs.

Transformer module that distorts input using turbulent noise. One input.

Caches the source module value when evaluated at the same coordinates more than once. This can improve performance when an expensive module may be evaluated more than once within a single noise tree. One input.

Constant noise module. Returns a constant value at any location. Zero inputs.

Selects one of two noise modules based on the output of the control module and the set bounds. Three inputs.

Returns a gradient in the y-axis mapped from zero to one. Zero inputs.

Returns the minimum of two noise modules. Two inputs.

Returns the maximum of two noise modules. Two inputs.

Returns the addition of two noise modules. Two inputs.

Returns the multiplication of two noise modules. Two inputs.

Returns the negative of the source noise module. One inputs.

Returns the absolute version of the source noise module. One input.

Returns the first non-zero value of two noise modules. Two inputs.

Scales and offsets the output of a noise module. One input.

Displaces the coordinates of a noise module using three other noise modules. Four inputs.

Scales the coordinates of the input source module. One input.