A single voxel

The simplest functional script draws a single voxel at the world origin. Set the contents of main.lua to this:

-- Lines that start with two dashes are comments
-- to help other humans. The computer ignores them!

-- Create a reference to our world origin coordinate
worldOrigin = {0, 0, 0}

-- Set up a red voxel to draw with later
reddishVoxel = {
  color = {255, 10, 20},
  layer = Cosm.LayerType.Solid
}

-- The "Start" function is run once when the script play button is
-- tapped in the Microcosm user interface.
function start()
  -- Use the DrawVoxel method to place our voxel
  -- at the world origin
  Cosm.currentWorld:drawVoxel(
    worldOrigin,
    reddishVoxel,
    Cosm.DrawMode.Set
  )
end

Erasing

Let’s make another script to erase the voxel at the world origin. It’s always good to clean up after yourself!

worldOrigin = {0, 0, 0}

function start()
	Cosm.currentWorld:drawVoxel(
    worldOrigin,
    nil,
    -- DrawMode.Set would also work here!
    Cosm.DrawMode.Delete
  )
end

The cursor

Instead of drawing in the same spot every time, let’s try drawing something where the user is looking:

-- If you're curious why `local` is used below,
-- check out [<https://www.lua.org/pil/4.2.html>](<https://www.lua.org/pil/4.2.html>)
local blueVoxel = {
  color = {0, 0, 255},
  layer = Cosm.LayerType.Solid
}

function start()
  -- Cursor.Coord returns the coordinate the user
  -- is currently looking at, e.g. {50, 80, -200}
  local startCoord = Cosm.cursor.coord

  -- Use "square bracket notation" to create a new
  -- coordinate that's slightly offset from where
  -- the player is looking. Using the example coordinates
  -- from above, this would give {55, 83, -193)
  local endCoord = {
		startCoord[1] + 5,
		startCoord[2] + 3,
		startCoord[3] + 7
	}

  -- Draw a line with one end at the cursor,
  -- and the other end at our offset position
  Cosm.currentWorld:drawLine(
    startCoord,
    endCoord,
    blueVoxel,
    Cosm.DrawMode.Set
  )
end

Undo

So far, all of the draw* commands we’ve used have been permanent. You can add draw* commands to the undo history by setting the addHistoryState option to true. Use this undo functionality thoughtfully and sparingly; it does come with a performance cost.

It’s worth noting that the Microcosm undo history state can currently hold a maximum of 50 entries. This number should help inform your use of the addHistoryState option.

local blueVoxel = {
  color = {0, 0, 255},
  layer = Cosm.LayerType.Solid
}

function start()
  Cosm.currentWorld:drawVoxel(
    Cosm.cursor.coord,
    blueVoxel,
    Cosm.DrawMode.Set,
    -- Specifying `true` as the last argument to a
    -- draw command adds a history state.
    true
  )
end

Logging

The standard Lua print function is redirected to the scripting logs drawer. This can be useful for debugging. More informational text can be displayed using Microcosm’s top of screen “toast messages” by calling Cosm.toast:add(message, duration).

function start()
  -- Sent to scripting logs drawer
  print("Hello, cool world!")
end

function start()
  -- Displayed at the top of the screen as a "toast message"
  Cosm.toast:add(
    "Hello, cool world!",
    3 -- Optional, duration in seconds. Defaults to 5
  )
end