Pine3D

https://pine3d.cc/docs/
Admin
Pine3D is a lightweight 3D graphics library for ComputerCraft that allows players to render 3D...
Tokens:10,784
Snippets:107
Trust Score:4.8
Update:2 months ago
Show doc for...
Tokens:
Raw
### Full Pine3D Example

Source: https://pine3d.cc/docs/guide/1_gettingStarted

Complete script combining initialization, configuration, object definition, and rendering.

```lua
local Pine3D = require("Pine3D")

local ThreeDFrame = Pine3D.newFrame() -- x1, y1, x2, y2 (default is fullscreen)
ThreeDFrame:setCamera(0, 0.6, 0) -- x, y, z, rotations around all axes (optional)
ThreeDFrame:setFoV(60) -- set the field of view

local objects = {
  -- args: modelId, x, y, z, rotations around all axes (optional)
  ThreeDFrame:newObject("models/pineapple", 2, 0, 0, nil, math.pi*0.25, nil),
}

ThreeDFrame:drawObjects(objects)
ThreeDFrame:drawBuffer()
sleep(1)
```

--------------------------------

### Install Pine3D

Source: https://pine3d.cc/docs/guide/1_gettingStarted

Command to download the library and its dependencies.

```shell
pastebin run qpJYiYs2
```

--------------------------------

### Full environment rendering example

Source: https://pine3d.cc/docs/guide/5_simpleSkybox

Demonstrates the complete process of initializing a frame, creating environment objects, and rendering them before standard scene objects.

```lua
-- import library
local Pine3D = require("Pine3D")

-- create a new frame
local ThreeDFrame = Pine3D.newFrame()

-- create environment objects
local environmentObjects = {
  ThreeDFrame:newObject(Pine3D.models:mountains({
    color = colors.lightGray,
    y = -0.1,
    res = 12,
    scale = 100,
    randomHeight = 0.5,
    randomOffset = 0.5,
    snow = true,
    snowHeight = 0.6,
  })),
  ThreeDFrame:newObject(Pine3D.models:mountains({
    color = colors.green,
    y = -0.1,
    res = 18,
    scale = 50,
    randomHeight = 0.5,
    randomOffset = 0.5,
  })),
  ThreeDFrame:newObject(Pine3D.models:plane({
    color = colors.lime,
    size = 100,
    y = -0.1,
  })),
}

-- create objects to render normally
local objects = {
  ThreeDFrame:newObject("models/pineapple", 1.5, -0.7, 0, nil, math.pi*0.125, nil)
}

-- render environment before the other objects
ThreeDFrame:drawObjects(environmentObjects)
ThreeDFrame:drawObjects(objects)
ThreeDFrame:drawBuffer()

-- sleep to see the result for a second
sleep(1)
```

--------------------------------

### Full Interactive Example

Source: https://pine3d.cc/docs/guide/3_mouseInput

A complete program demonstrating how to render a grid of boxes and remove them from the scene when clicked.

```lua
local Pine3D = require("Pine3D")

local ThreeDFrame = Pine3D.newFrame()
ThreeDFrame:setCamera(-1, 0, -1, 0, 45, -45)

local objects = {}

-- create a grid of boxes with the specified grid size
local size = 3
for x = 1, size do
  for y = 1, size do
    for z = 1, size do
      objects[#objects+1] = ThreeDFrame:newObject("models/box", x, y-size*2, z)
    end
  end
end

while true do
  -- render the scene
  ThreeDFrame:drawObjects(objects)
  ThreeDFrame:drawBuffer()

  -- wait for user input
  local event, key, x, y = os.pullEvent()

  -- check if the event was a click
  if event == "mouse_click" then
    -- pass the rendered objects with the coordinates of the clicked pixel
    local objectIndex, polyIndex = ThreeDFrame:getObjectIndexTrace(objects, x, y)
    if objectIndex then -- check if an object was clicked
	  -- remove the object from the list of rendered objects
      table.remove(objects, objectIndex)
    end
  end
end
```

--------------------------------

### Full Pine3D Game Example

Source: https://pine3d.cc/docs/guide/4_baseGame

A complete implementation demonstrating camera movement, object animation, and the main execution loop.

```lua
local Pine3D = require("Pine3D")

-- movement and turn speed of the camera
local speed = 2 -- units per second
local turnSpeed = 180 -- degrees per second

-- create a new frame
local ThreeDFrame = Pine3D.newFrame()

-- initialize our own camera and update the frame camera
local camera = {
  x = 0,
  y = 0,
  z = 0,
  rotX = 0,
  rotY = 0,
  rotZ = 0,
}
ThreeDFrame:setCamera(camera)

-- define the objects to be rendered
local objects = {
  ThreeDFrame:newObject("models/pineapple", 0, 0, 0), -- pineapple at 0, 0, 0
}

-- handle all keypresses and store in a lookup table
-- to check later if a key is being pressed
local keysDown = {}
local function keyInput()
  while true do
    -- wait for an event
    local event, key, x, y = os.pullEvent()

    if event == "key" then -- if a key is pressed, mark it as being pressed down
      keysDown[key] = true
    elseif event == "key_up" then -- if a key is released, reset its value
      keysDown[key] = nil
    end
  end
end

-- update the camera position based on the keys being pressed
-- and the time passed since the last step
local function handleCameraMovement(dt)
  local dx, dy, dz = 0, 0, 0 -- will represent the movement per second

  -- handle arrow keys for camera rotation
  if keysDown[keys.left] then
    camera.rotY = (camera.rotY - turnSpeed * dt) % 360
  end
  if keysDown[keys.right] then
    camera.rotY = (camera.rotY + turnSpeed * dt) % 360
  end
  if keysDown[keys.down] then
    camera.rotZ = math.max(-80, camera.rotZ - turnSpeed * dt)
  end
  if keysDown[keys.up] then
    camera.rotZ = math.min(80, camera.rotZ + turnSpeed * dt)
  end

  -- handle wasd keys for camera movement
  if keysDown[keys.w] then
    dx = speed * math.cos(math.rad(camera.rotY)) + dx
    dz = speed * math.sin(math.rad(camera.rotY)) + dz
  end
  if keysDown[keys.s] then
    dx = -speed * math.cos(math.rad(camera.rotY)) + dx
    dz = -speed * math.sin(math.rad(camera.rotY)) + dz
  end
  if keysDown[keys.a] then
    dx = speed * math.cos(math.rad(camera.rotY - 90)) + dx
    dz = speed * math.sin(math.rad(camera.rotY - 90)) + dz
  end
  if keysDown[keys.d] then
    dx = speed * math.cos(math.rad(camera.rotY + 90)) + dx
    dz = speed * math.sin(math.rad(camera.rotY + 90)) + dz
  end

  -- space and left shift key for moving the camera up and down
  if keysDown[keys.space] then
    dy = speed + dy
  end
  if keysDown[keys.leftShift] then
    dy = -speed + dy
  end

  -- update the camera position by adding the offset
  camera.x = camera.x + dx * dt
  camera.y = camera.y + dy * dt
  camera.z = camera.z + dz * dt

  ThreeDFrame:setCamera(camera)
end

-- handle game logic
local function handleGameLogic(dt)
  -- set y coordinate to move up and down based on time
  objects[1]:setPos(nil, math.sin(os.clock())*0.25, nil)

  -- set horizontal rotation depending on the time
  objects[1]:setRot(nil, os.clock(), nil)
end

-- handle the game logic and camera movement in steps
local function gameLoop()
  local lastTime = os.clock()

  while true do
    -- compute the time passed since last step
    local currentTime = os.clock()
    local dt = currentTime - lastTime
    lastTime = currentTime

    -- run all functions that need to be run
    handleGameLogic(dt)
    handleCameraMovement(dt)

    -- use a fake event to yield the coroutine
    os.queueEvent("gameLoop")
    os.pullEventRaw("gameLoop")
  end
end

-- render the objects
local function rendering()
  while true do
    -- load all objects onto the buffer and draw the buffer
    ThreeDFrame:drawObjects(objects)
    ThreeDFrame:drawBuffer()

    -- use a fake event to yield the coroutine
    os.queueEvent("rendering")
    os.pullEventRaw("rendering")
  end
end

-- start the functions to run in parallel
parallel.waitForAny(keyInput, gameLoop, rendering)
```

--------------------------------

### Execute Parallel Tasks

Source: https://pine3d.cc/docs/guide/4_baseGame

Starts the input, game logic, and rendering functions concurrently.

```lua
-- start the functions to run in parallel
parallel.waitForAny(keyInput, gameLoop, rendering)
```

--------------------------------

### Generate 3D Models with Pine3D

Source: https://pine3d.cc/docs/class/ModelGenerator

Examples of creating various 3D models using the Pine3D.models generator methods.

```lua
local models = Pine3D.models

-- creates a very simple grass block model
local cube = models:cube({
  color = colors.orange,
  top = colors.lime,
  bottom = colors.brown,
})

-- trans colored sphere
local sphere = models:sphere({
  res = 7,
  colors = {
    colors.lightBlue,
    colors.pink,
    colors.white,
    colors.pink,
    colors.lightBlue,
  },
}

-- fractal colored icosphere
local icosphere = models:icosphere({
  res = 3,
  colors = {
    colors.red,
    colors.yellow,
    colors.lime,
  },
  colorsFractal = true,
})

-- 12 gray mountains with randomized height and snow
local mountains = models:mountains({
  color = colors.lightGray,
  y = -0.1,
  res = 12,
  scale = 100,
  randomHeight = 0.5,
  randomOffset = 0.5,
  snow = true,
  snowHeight = 0.6,
})
```

--------------------------------

### Creating and Using an LoDModel

Source: https://pine3d.cc/docs/class/LoDModel

Demonstrates how to convert a standard model into an LoDModel with custom settings and instantiate multiple objects using it.

```lua
-- load pinetree model
local pinetree = Pine3D.loadModel("models/pinetree"):alignBottom():normalizeScaleY()

-- we can easily convert the model to an LoDModel:
-- local pinetreeLoD = pinetree:toLoD()

-- or we can specify settings for the Level of Detail:
local pinetreeLoD = pinetree:toLoD({
  minQuality = 0.1, -- default: 0.1 (optional)
  variantCount = 5, -- default: 4 (optional)
  qualityHalvingDistance = 8, -- default: 5 (optional)
  quickInitWorseRuntime = false, -- default: false (optional)
})

-- we create a table for our objects
local objects = {}

-- simply create a new objects with the LoDModel
for i = 1, 100 do -- how many pinetrees
  local x = math.random(1, 20)
  local z = math.random(1, 20)
  local pinetree = ThreeDFrame:newObject(pinetreeLoD, x, 0, z)
  objects[i] = pinetree
end
```

--------------------------------

### Import Pine3D

Source: https://pine3d.cc/docs/guide/1_gettingStarted

Initializes the library using the require method.

```lua
local Pine3D = require("Pine3D")
```

--------------------------------

### Initialize Camera

Source: https://pine3d.cc/docs/guide/4_baseGame

Define the camera object and apply it to the ThreeDFrame.

```lua
-- initialize our own camera and update the frame camera
local camera = {
  x = 0,
  y = 0,
  z = 0,
  rotX = 0,
  rotY = 0,
  rotZ = 0,
}
ThreeDFrame:setCamera(camera)
```

--------------------------------

### Manage Camera via Table

Source: https://pine3d.cc/docs/guide/2_manageCamera

Demonstrates tracking camera state in a table and applying it to the frame.

```lua
local camera = {
  x = 1, -- x
  y = 10, -- y
  z = 1, -- z
  rotX = 0, -- rotation around x axis
  rotY = 0, -- rotation around y axis
  rotZ = 0, -- rotation around z axis
}

-- set values one by one
ThreeDFrame:setCamera(camera.x, camera.y, camera.z,
	camera.rotX, camera.rotY, camera.rotZ)

-- pass the camera
ThreeDFrame:setCamera(camera)
```

--------------------------------

### Create ThreeDFrame

Source: https://pine3d.cc/docs/guide/4_baseGame

Initialize a new 3D frame instance.

```lua
-- create a new frame
local ThreeDFrame = Pine3D.newFrame()
```

--------------------------------

### Create a new ThreeDFrame

Source: https://pine3d.cc/docs/class/ThreeDFrame

Initializes a new rendering environment using the Pine3D library.

```lua
local frame = Pine3D:newFrame(x1, y1, x2, y2)
```

--------------------------------

### Transforming and Manipulating Models

Source: https://pine3d.cc/docs/class/Model

Demonstrates loading a model, applying outline and color mappings, chaining transformation methods, and creating a new object from the model.

```lua
-- load pineapple model
local pineapple = Pine3D.loadModel("models/pineapple")

-- set the outline to green for lime polygons
pineapple = pineapple:setOutline({
  [colors.lime] = colors.green,
})

-- these can be chained as well:
pineapple = pineapple:rotate(math.pi*0.5):scale(2):mapColor({
  [colors.yellow] = colors.lightBlue,
  [colors.orange] = colors.pink,
})

-- simply create a new object using the created model
local pineappleObject = ThreeDFrame:newObject(pineapple, 0, 0, 0)
```

--------------------------------

### Create a 3D Frame

Source: https://pine3d.cc/docs/guide/1_gettingStarted

Initializes a new frame; defaults to full terminal size if no dimensions are provided.

```lua
-- params: x1, y1, x2, y2
local ThreeDFrame = Pine3D.newFrame() -- x1, y1, x2, y2 (default is fullscreen)
```

--------------------------------

### icosphere(options)

Source: https://pine3d.cc/docs/class/ModelGenerator

Creates an icosphere model with support for gradients and fractal coloring.

```APIDOC
## icosphere(options)

### Description
Creates an icosphere model.

### Parameters
- **options** (table) - Optional - Configuration table. Available keys: res, color, top, bottom, colors, colorsFractal.
```

--------------------------------

### Handle Key Input

Source: https://pine3d.cc/docs/guide/4_baseGame

Track key states in a lookup table using os.pullEvent.

```lua
-- handle all keypresses and store in a lookup table
-- to check later if a key is being pressed
local keysDown = {}
local function keyInput()
  while true do
    -- wait for an event
    local event, key, x, y = os.pullEvent()

    if event == "key" then -- if a key is pressed, mark it as being pressed down
      keysDown[key] = true
    elseif event == "key_up" then -- if a key is released, reset its value
      keysDown[key] = nil
    end
  end
end
```

--------------------------------

### cube(options)

Source: https://pine3d.cc/docs/class/ModelGenerator

Creates a cube model with customizable colors for different faces.

```APIDOC
## cube(options)

### Description
Creates a simple cube model.

### Parameters
- **options** (table) - Optional - Configuration table. Available keys: color, bottom, bottom2, top, top2, side, side2.
```

--------------------------------

### plane(options)

Source: https://pine3d.cc/docs/class/ModelGenerator

Creates a flat plane model.

```APIDOC
## plane(options)

### Description
Creates a flat plane model.

### Parameters
- **options** (table) - Optional - Configuration table. Available keys: color, size, y.
```

--------------------------------

### LoDModel:initObject

Source: https://pine3d.cc/docs/class/LoDModel

Initializes a PineObject to use the LoDModel system.

```APIDOC
## LoDModel:initObject(object)

### Description
Prepares a PineObject to be managed by the LoDModel system.

### Parameters
- **object** (PineObject) - Required - The object to initialize.
```

--------------------------------

### Implement Game Loop

Source: https://pine3d.cc/docs/guide/4_baseGame

Manage game logic updates and the main loop execution timing.

```lua
-- handle game logic
local function handleGameLogic(dt)
  -- set y coordinate to move up and down based on time
  objects[1]:setPos(nil, math.sin(os.clock())*0.25, nil)

  -- set horizontal rotation depending on the time
  objects[1]:setRot(nil, os.clock(), nil)
end

-- handle the game logic and camera movement in steps
local function gameLoop()
  local lastTime = os.clock()

  while true do
    -- compute the time passed since last step
    local currentTime = os.clock()
    local dt = currentTime - lastTime
    lastTime = currentTime

    -- run all functions that need to be run
    handleGameLogic(dt)
    handleCameraMovement(dt)

    -- use a fake event to yield the coroutine
    os.queueEvent("gameLoop")
    os.pullEventRaw("gameLoop")
  end
end
```

--------------------------------

### Configure Camera and FoV

Source: https://pine3d.cc/docs/guide/1_gettingStarted

Sets the camera position and field of view for the frame.

```lua
ThreeDFrame:setCamera(0, 0.6, 0) -- x, y, z, rotations around all axes (optional)
ThreeDFrame:setFoV(60) -- set the field of view
```

--------------------------------

### sphere(options)

Source: https://pine3d.cc/docs/class/ModelGenerator

Creates a sphere model with customizable resolution and color.

```APIDOC
## sphere(options)

### Description
Creates a sphere model.

### Parameters
- **options** (table) - Optional - Configuration table. Available keys: res, color.
```

--------------------------------

### Convert .obj model using objConverter.lua

Source: https://pine3d.cc/docs/guide/6_creatingModels

Run the converter script to process an .obj file into the Pine3D model format.

```lua
objConverter.lua
```

--------------------------------

### Define Rendering Loop

Source: https://pine3d.cc/docs/guide/4_baseGame

Loads objects into the buffer and draws them within a coroutine-friendly loop.

```lua
-- render the objects
local function rendering()
  while true do
    -- load all objects onto the buffer and draw the buffer
    ThreeDFrame:drawObjects(objects)
    ThreeDFrame:drawBuffer()

    -- use a fake event to yield the coroutine
    os.queueEvent("rendering")
    os.pullEventRaw("rendering")
  end
end
```

--------------------------------

### Create a plane object

Source: https://pine3d.cc/docs/guide/5_simpleSkybox

Generates a flat plane model positioned just below the camera.

```lua
local plane = ThreeDFrame:newObject(Pine3D.models:plane({
  color = colors.lime,
  size = 100,
  y = -0.1,
}))
```

--------------------------------

### Render Objects

Source: https://pine3d.cc/docs/guide/1_gettingStarted

Draws the defined objects to the buffer and displays the result.

```lua
ThreeDFrame:drawObjects(objects)
ThreeDFrame:drawBuffer()
sleep(1)
```

--------------------------------

### Create a PineObject

Source: https://pine3d.cc/docs/class/PineObject

Instantiate a new PineObject using the ThreeDFrame:newObject method.

```lua
-- creates a PineObject with the pineapple model at 1, 3, 7
local object = ThreeDFrame:newObject("pineapple", 1, 3, 7)
```

--------------------------------

### Create a mountains object

Source: https://pine3d.cc/docs/guide/5_simpleSkybox

Generates a mountain model with snow-capped peaks by enabling the snow property.

```lua
local mountains = ThreeDFrame:newObject(Pine3D.models:mountains({
  color = colors.lightGray,
  y = -0.1,
  res = 12,
  scale = 100,
  randomHeight = 0.5,
  randomOffset = 0.5,
  snow = true,
  snowHeight = 0.6,
}))
```

--------------------------------

### Define Render Objects

Source: https://pine3d.cc/docs/guide/4_baseGame

Create a table of objects to be rendered within the frame.

```lua
-- define the objects to be rendered
local objects = {
  ThreeDFrame:newObject("models/pineapple", 0, 0, 0), -- pineapple at 0, 0, 0
}
```

--------------------------------

### Update Camera Position

Source: https://pine3d.cc/docs/guide/4_baseGame

Calculate camera movement and rotation based on delta time and active key inputs.

```lua
-- update the camera position based on the keys being pressed
-- and the time passed since the last step
local function handleCameraMovement(dt)
  local dx, dy, dz = 0, 0, 0 -- will represent the movement per second

  -- handle arrow keys for camera rotation
  if keysDown[keys.left] then
    camera.rotY = (camera.rotY - turnSpeed * dt) % 360
  end
  if keysDown[keys.right] then
    camera.rotY = (camera.rotY + turnSpeed * dt) % 360
  end
  if keysDown[keys.down] then
    camera.rotZ = math.max(-80, camera.rotZ - turnSpeed * dt)
  end
  if keysDown[keys.up] then
    camera.rotZ = math.min(80, camera.rotZ + turnSpeed * dt)
  end

  -- handle wasd keys for camera movement
  if keysDown[keys.w] then
    dx = speed * math.cos(math.rad(camera.rotY)) + dx
    dz = speed * math.sin(math.rad(camera.rotY)) + dz
  end
  if keysDown[keys.s] then
    dx = -speed * math.cos(math.rad(camera.rotY)) + dx
    dz = -speed * math.sin(math.rad(camera.rotY)) + dz
  end
  if keysDown[keys.a] then
    dx = speed * math.cos(math.rad(camera.rotY - 90)) + dx
    dz = speed * math.sin(math.rad(camera.rotY - 90)) + dz
  end
  if keysDown[keys.d] then
    dx = speed * math.cos(math.rad(camera.rotY + 90)) + dx
    dz = speed * math.sin(math.rad(camera.rotY + 90)) + dz
  end

  -- space and left shift key for moving the camera up and down
  if keysDown[keys.space] then
    dy = speed + dy
  end
  if keysDown[keys.leftShift] then
    dy = -speed + dy
  end

  -- update the camera position by adding the offset
  camera.x = camera.x + dx * dt
  camera.y = camera.y + dy * dt
  camera.z = camera.z + dz * dt

  ThreeDFrame:setCamera(camera)
end
```

--------------------------------

### Define Camera Movement Constants

Source: https://pine3d.cc/docs/guide/4_baseGame

Set the movement and rotation speed for the camera.

```lua
-- movement and turn speed of the camera
local speed = 2 -- units per second
local turnSpeed = 180 -- degrees per second
```

--------------------------------

### mountains(options)

Source: https://pine3d.cc/docs/class/ModelGenerator

Creates a mountain range model with randomized height and snow features.

```APIDOC
## mountains(options)

### Description
Creates a mountain range model.

### Parameters
- **options** (table) - Optional - Configuration table. Available keys: res, randomOffset, height, randomHeight, y, scale, color, snow, snowColor.
```

--------------------------------

### Define 3D Objects

Source: https://pine3d.cc/docs/guide/1_gettingStarted

Creates a list of objects to be rendered using model IDs and coordinates.

```lua
local objects = {
  -- args: modelId, x, y, z, rotations around all axes (optional)
  ThreeDFrame:newObject("models/pineapple", 2, 0, 0, nil, math.pi*0.25, nil),
}
```

--------------------------------

### Set Camera Position and Orientation

Source: https://pine3d.cc/docs/guide/2_manageCamera

Sets all camera parameters simultaneously using coordinate and rotation values.

```lua
ThreeDFrame:setCamera(x, y, z, rotationX, rotationY, rotationZ)
```

--------------------------------

### Define a custom cube model in Lua

Source: https://pine3d.cc/docs/guide/6_creatingModels

Uses a helper function to construct polygons and defines a cube model with configurable colors for different faces.

```lua
-- helper function to create a new Polygon
function newPoly(x1, y1, z1, x2, y2, z2, x3, y3, z3, c)
  return {
    x1 = x1, y1 = y1, z1 = z1, x2 = x2, y2 = y2, z2 = z2, x3 = x3, y3 = y3, z3 = z3,
    c = c,
  }
end
function models:cube(o)
  o.color = o.color or colors.red
  return {
    newPoly(-.5,-.5,-.5, .5,-.5,.5, -.5,-.5,.5, o.bottom or o.color),
    newPoly(-.5,-.5,-.5, .5,-.5,-.5, .5,-.5,.5, o.bottom2 or o.bottom or o.color),
    newPoly(-.5,.5,-.5, -.5,.5,.5, .5,.5,.5, o.top or o.color),
    newPoly(-.5,.5,-.5, .5,.5,.5, .5,.5,-.5, o.top or o.color),
    newPoly(-.5,-.5,-.5, -.5,-.5,.5, -.5,.5,-.5, o.side or o.color),
    newPoly(-.5,-.5,.5, -.5,.5,.5, -.5,.5,-.5, o.side2 or o.side or o.color),
    newPoly(.5,-.5,-.5, .5,.5,.5, .5,-.5,.5, o.side or o.color),
    newPoly(.5,-.5,-.5, .5,.5,-.5, .5,.5,.5, o.side2 or o.side or o.color),
    newPoly(-.5,-.5,-.5, .5,.5,-.5, .5,-.5,-.5, o.side or o.color),
    newPoly(-.5,-.5,-.5, -.5,.5,-.5, .5,.5,-.5, o.side2 or o.side or o.color),
    newPoly(-.5,-.5,.5, .5,-.5,.5, -.5,.5,.5, o.side or o.color),
    newPoly(.5,-.5,.5, .5,.5,.5, -.5,.5,.5, o.side2 or o.side or o.color),
  }
end
```

--------------------------------

### Create a hills object

Source: https://pine3d.cc/docs/guide/5_simpleSkybox

Generates a hilly terrain model using the mountains method with specific color and resolution settings.

```lua
local hills = ThreeDFrame:newObject(Pine3D.models:mountains({
  color = colors.green,
  y = -0.1,
  res = 18,
  scale = 50,
  randomHeight = 0.5,
  randomOffset = 0.5,
}))
```

--------------------------------

### Update Specific Camera Parameter

Source: https://pine3d.cc/docs/guide/2_manageCamera

Uses nil values to skip parameters, allowing for targeted updates like horizontal rotation.

```lua
ThreeDFrame:setCamera(nil, nil, nil, nil, ThreeDFrame.camera[5] + 90, nil)
```

--------------------------------

### Buffer:setBufferSize

Source: https://pine3d.cc/docs/class/Buffer

Configures the dimensions of the buffer's window.

```APIDOC
## Buffer:setBufferSize(x1, y1, x2, y2)

### Description
Sets the starting and ending positions of the buffer's window.

### Parameters
- **x1** (number) - x of starting position of the buffer's window.
- **y1** (number) - y of starting position of the buffer's window.
- **x2** (number) - x of ending position of the buffer's window.
- **y2** (number) - y of ending position of the buffer's window.
```

--------------------------------

### Model:alignBottom

Source: https://pine3d.cc/docs/class/Model

Aligns the model to the bottom.

```APIDOC
## Model:alignBottom()

### Description
Returns a new model aligned to the bottom.

### Returns
- **Model** - The aligned model.
```

--------------------------------

### ThreeDFrame:setSize

Source: https://pine3d.cc/docs/class/ThreeDFrame

Updates the dimensions and position of the 3D rendering window.

```APIDOC
## ThreeDFrame:setSize(x1, y1, x2, y2)

### Description
Sets the starting and ending coordinates for the 3D rendering window.

### Parameters
- **x1** (number) - x of starting position of the 3d rendering window
- **y1** (number) - y of starting position of the 3d rendering window
- **x2** (number) - x of ending position of the 3d rendering window
- **y2** (number) - y of ending position of the 3d rendering window
```

--------------------------------

### Model:toLoD

Source: https://pine3d.cc/docs/class/LoDModel

Converts an existing Model into an LoDModel with optional configuration settings for quality and variants.

```APIDOC
## Model:toLoD(settings)

### Description
Converts a standard model into an LoDModel. This allows the engine to switch between model variants based on distance to the camera.

### Parameters
- **settings** (table) - Optional - Configuration table containing:
  - **minQuality** (number) - The quality level for the lowest-quality variant (default: 0.1).
  - **variantCount** (number) - Number of lower-quality variants to generate (default: 4).
  - **qualityHalvingDistance** (number) - Distance from camera where quality is halved (default: 5).
  - **quickInitWorseRuntime** (boolean) - If true, uses the same CollapsedModel for all variants to speed up initialization at the cost of runtime performance (default: false).
```

--------------------------------

### Model:center

Source: https://pine3d.cc/docs/class/Model

Centers the model geometry.

```APIDOC
## Model:center()

### Description
Returns a new centered version of the model.

### Returns
- **Model** - The centered model.
```

--------------------------------

### Model:setOutline

Source: https://pine3d.cc/docs/class/Model

Sets the outline color for the model's polygons.

```APIDOC
## Model:setOutline(options)

### Description
Returns a new model with updated outline colors based on the provided options.

### Parameters
- **options** (color or table) - Required - If color, sets the outline color for each polygon. If table, maps existing triangle colors to new outline colors.

### Returns
- **Model** - The model with updated outlines.
```

--------------------------------

### Detecting Mouse Clicks

Source: https://pine3d.cc/docs/guide/3_mouseInput

Use os.pullEvent to listen for mouse_click events and pass coordinates to getObjectIndexTrace to identify clicked objects.

```lua
local ThreeDFrame = ... -- the frame defined at the start of your program
local objects = { ... } -- the list of objects defined earlier in your program

-- ...

while true do
  local event, key, x, y = os.pullEvent()

  -- check if the event was a click
  if event == "mouse_click" then
    -- pass the rendered objects with the coordinates of the clicked pixel
    local objectIndex, polyIndex = ThreeDFrame:getObjectIndexTrace(objects, x, y)
  end
end
```

--------------------------------

### Buffer:image

Source: https://pine3d.cc/docs/class/Buffer

Draws an image onto the buffer at the specified coordinates.

```APIDOC
## Buffer:image(x, y, image)

### Description
Draws an image loaded with paintutils at the specified coordinates.

### Parameters
- **x** (number) - The x-coordinate.
- **y** (number) - The y-coordinate.
- **image** (PaintUtilsImage) - The image object to draw.
```

--------------------------------

### ThreeDFrame:drawBuffer

Source: https://pine3d.cc/docs/class/ThreeDFrame

Renders the current buffer to the screen.

```APIDOC
## ThreeDFrame:drawBuffer()

### Description
Draws the contents of the internal buffer to the display.
```

--------------------------------

### ThreeDFrame:newObject

Source: https://pine3d.cc/docs/class/ThreeDFrame

Creates and adds a new object to the rendering frame.

```APIDOC
## ThreeDFrame:newObject(model, x, y, z, rotX, rotY, rotZ)

### Description
Loads a model and places it at the specified coordinates.

### Parameters
- **model** (string or Model) - Path to load the serialized Model
- **x** (number) - x coordinate
- **y** (number) - y coordinate
- **z** (number) - z coordinate
- **rotX** (number) - Optional rotation around x axis
- **rotY** (number) - Optional rotation around y axis
- **rotZ** (number) - Optional rotation around z axis
```

--------------------------------

### Model:scale

Source: https://pine3d.cc/docs/class/Model

Scales the model by a factor.

```APIDOC
## Model:scale(scale)

### Description
Returns a new model scaled by the specified factor.

### Parameters
- **scale** (number) - Required - The factor to scale the model.

### Returns
- **Model** - The scaled model.
```

--------------------------------

### Set Field of View

Source: https://pine3d.cc/docs/guide/2_manageCamera

Adjusts the camera field of view in degrees.

```lua
ThreeDFrame:setFoV(60) -- 60 degrees
```

--------------------------------

### Model:rotate

Source: https://pine3d.cc/docs/class/Model

Rotates the model.

```APIDOC
## Model:rotate(rotX, rotY, rotZ)

### Description
Returns a new model rotated by the specified radians.

### Parameters
- **rotX** (number) - Optional - Rotation around the x-axis.
- **rotY** (number) - Optional - Rotation around the y-axis.
- **rotZ** (number) - Optional - Rotation around the z-axis.

### Returns
- **Model** - The rotated model.
```

--------------------------------

### Model:mapColor

Source: https://pine3d.cc/docs/class/Model

Updates the colors of the model's polygons.

```APIDOC
## Model:mapColor(options)

### Description
Returns a new model with updated colors based on the provided mapping.

### Parameters
- **options** (color or table) - Required - If color, sets the color for each polygon. If table, maps existing triangle colors to new colors.

### Returns
- **Model** - The model with updated colors.
```

--------------------------------

### Model:toLoD

Source: https://pine3d.cc/docs/class/Model

Converts the model to a Level of Detail (LoD) model.

```APIDOC
## Model:toLoD(options)

### Description
Returns a model that can render at lower quality based on distance from the camera.

### Parameters
- **options** (table) - Optional - Configuration table with keys: minQuality, variantCount, qualityHalvingDistance, quickInitWorseRuntime.

### Returns
- **LoDModel** - The LoD-enabled model.
```

--------------------------------

### PineCamera Properties

Source: https://pine3d.cc/docs/class/PineCamera

The PineCamera class exposes several properties for manipulating the camera's spatial state.

```APIDOC
## PineCamera Properties

### x
- **Type**: number
- **Description**: The x-coordinate position of the camera.

### y
- **Type**: number
- **Description**: The y-coordinate position of the camera.

### z
- **Type**: number
- **Description**: The z-coordinate position of the camera.

### rotationX
- **Type**: number
- **Description**: The camera rotation around the x-axis.

### rotationY
- **Type**: number
- **Description**: The camera rotation around the y-axis (horizontal rotation).

### rotationZ
- **Type**: number
- **Description**: The camera rotation around the z-axis (vertical rotation).
```

--------------------------------

### Model:translate

Source: https://pine3d.cc/docs/class/Model

Translates the model in 3D space.

```APIDOC
## Model:translate(dx, dy, dz)

### Description
Returns a new model translated by the specified offsets.

### Parameters
- **dx** (number) - Optional - Translation on the x-axis.
- **dy** (number) - Optional - Translation on the y-axis.
- **dz** (number) - Optional - Translation on the z-axis.

### Returns
- **Model** - The translated model.
```

--------------------------------

### Set Camera Position Only

Source: https://pine3d.cc/docs/guide/2_manageCamera

Updates the camera coordinates while leaving the current orientation unchanged.

```lua
ThreeDFrame:setCamera(x, y, z)
```

--------------------------------

### ThreeDFrame:setCamera

Source: https://pine3d.cc/docs/guide/2_manageCamera

Sets the camera position and orientation. Can be called with individual coordinates or a camera table object.

```APIDOC
## ThreeDFrame:setCamera

### Description
Sets the camera position (x, y, z) and orientation (rotationX, rotationY, rotationZ). You can provide individual arguments or a table containing the camera properties.

### Signature
`ThreeDFrame:setCamera(x, y, z, rotationX, rotationY, rotationZ)`
`ThreeDFrame:setCamera(cameraTable)`

### Parameters
- **x** (number) - Optional - The x-coordinate position.
- **y** (number) - Optional - The y-coordinate position.
- **z** (number) - Optional - The z-coordinate position.
- **rotationX** (number) - Optional - Rotation around the x-axis.
- **rotationY** (number) - Optional - Rotation around the y-axis.
- **rotationZ** (number) - Optional - Rotation around the z-axis.
- **cameraTable** (table) - Optional - A table containing x, y, z, rotX, rotY, and rotZ keys.
```

--------------------------------

### ThreeDFrame:setFoV

Source: https://pine3d.cc/docs/guide/2_manageCamera

Sets the field of view for the camera.

```APIDOC
## ThreeDFrame:setFoV

### Description
Sets the camera field of view in degrees.

### Signature
`ThreeDFrame:setFoV(fov)`

### Parameters
- **fov** (number) - Required - The field of view angle in degrees.
```

--------------------------------

### PineObject:setModel(model)

Source: https://pine3d.cc/docs/class/PineObject

Changes the model associated with the PineObject.

```APIDOC
## PineObject:setModel(model)

### Description
Sets the model to be rendered for this object.

### Parameters
- **model** (string or Model) - Required - If string, used as path to load the serialized Model

### Returns
- **void**
```

--------------------------------

### LoDModel:update

Source: https://pine3d.cc/docs/class/LoDModel

Updates the model variant for a specific object based on its distance to the camera.

```APIDOC
## LoDModel:update(object, camera)

### Description
Calculates and applies the appropriate model quality variant for an object based on its distance from the provided camera.

### Parameters
- **object** (PineObject) - Required - The object to update.
- **camera** (CollapsedCamera) - Required - The camera used for distance calculation.
```

--------------------------------

### PineObject:setPos(x, y, z)

Source: https://pine3d.cc/docs/class/PineObject

Updates the position of the PineObject in 3D space.

```APIDOC
## PineObject:setPos(x, y, z)

### Description
Updates the x, y, and z coordinates of the object.

### Parameters
- **x** (number) - Optional - New x position
- **y** (number) - Optional - New y position
- **z** (number) - Optional - New z position

### Returns
- **void**
```

--------------------------------

### Model:normalizeScale

Source: https://pine3d.cc/docs/class/Model

Normalizes the scale of the model.

```APIDOC
## Model:normalizeScale()

### Description
Returns a new model with normalized scale.

### Returns
- **Model** - The normalized model.
```

--------------------------------

### Buffer:setPixel

Source: https://pine3d.cc/docs/class/Buffer

Sets the color of a specific pixel in the buffer.

```APIDOC
## Buffer:setPixel(x, y, c)

### Description
Sets the color of a pixel at the specified coordinates.

### Parameters
- **x** (number) - The x-coordinate.
- **y** (number) - The y-coordinate.
- **c** (number) - The color for the pixel.
```

--------------------------------

### ThreeDFrame:setBackgroundColor

Source: https://pine3d.cc/docs/class/ThreeDFrame

Sets the background color for the rendering frame.

```APIDOC
## ThreeDFrame:setBackgroundColor(color)

### Description
Sets the background color using a CC color value.

### Parameters
- **color** (number) - CC color from the colors library
```

--------------------------------

### Model:decimate

Source: https://pine3d.cc/docs/class/Model

Reduces the polygon count of the model.

```APIDOC
## Model:decimate(quality, mode)

### Description
Returns a model with reduced quality.

### Parameters
- **quality** (number) - Required - Ratio of polys to keep or number of polys to reduce to.
- **mode** (string) - Optional - "ratio" or "polys". Default is "ratio".

### Returns
- **Model** - The decimated model.
```

--------------------------------

### Buffer:drawTriangle

Source: https://pine3d.cc/docs/class/Buffer

Draws a triangle in the buffer with optional depth interpolation.

```APIDOC
## Buffer:drawTriangle(x1, y1, x2, y2, x3, y3, c, depth, z1, z2, z3)

### Description
Draws a triangle with the specified vertices, color, and depth parameters.

### Parameters
- **x1, y1, x2, y2, x3, y3** (number) - Coordinates of the triangle vertices.
- **c** (number) - Fill color.
- **depth** (number) - Distance to the triangle.
- **z1, z2, z3** (number) - Depth for each vertex when interpolation is enabled.
```

--------------------------------

### PineObject:setRot(rotX, rotY, rotZ)

Source: https://pine3d.cc/docs/class/PineObject

Updates the rotation of the PineObject in radians.

```APIDOC
## PineObject:setRot(rotX, rotY, rotZ)

### Description
Updates the rotation of the object around the x, y, and z axes.

### Parameters
- **rotX** (number) - Optional - New rotation around the x axis in radians
- **rotY** (number) - Optional - New rotation around the y axis in radians
- **rotZ** (number) - Optional - New rotation around the z axis in radians

### Returns
- **void**
```

--------------------------------

### Model:normalizeScaleY

Source: https://pine3d.cc/docs/class/Model

Normalizes the Y-axis scale of the model.

```APIDOC
## Model:normalizeScaleY()

### Description
Returns a new model with normalized Y-axis scale.

### Returns
- **Model** - The normalized model.
```

--------------------------------

### Model:invertTriangles

Source: https://pine3d.cc/docs/class/Model

Inverts the direction of the polygons in the model.

```APIDOC
## Model:invertTriangles()

### Description
Returns a new model with polygons facing the opposite direction.

### Returns
- **Model** - The inverted model.
```
Tokens:
Raw