A turtle API client module for ComputerCraft that provides easy integration with the krawlet-api turtle tracking system. Features: Automatic stat tracking, position reporting, configurable API endpoint, periodic sync support, and simple state management for turtle data.
turtleApi
Recommended: Install via installer (handles dependencies automatically):
This pattern downloads and runs libraries at runtime, automatically installing any that are missing:
-- Auto-install and require libraries
local libs = {"turtle-tracker"} -- Add more libraries as needed
local libDir = (fs.exists("disk") and "disk/lib/" or "/lib/")
local allExist = true
for _, lib in ipairs(libs) do
if not fs.exists(libDir .. lib .. ".lua") then
allExist = false
break
end
end
if not allExist then
shell.run("wget", "run", "https://raw.githubusercontent.com/Twijn/cc-misc/main/util/installer.lua", table.unpack(libs))
end
local turtle-tracker = require(libDir .. "turtle-tracker")
-- Use the library
-- (your code here)
This example shows how to download and use libraries with automatic installation:
-- Auto-install and require libraries
local libs = {"turtle-tracker"} -- Add more libraries as needed
local libDir = (fs.exists("disk") and "disk/lib/" or "/lib/")
local allExist = true
for _, lib in ipairs(libs) do
if not fs.exists(libDir .. lib .. ".lua") then
allExist = false
break
end
end
if not allExist then
shell.run("wget", "run", "https://raw.githubusercontent.com/Twijn/cc-misc/main/util/installer.lua", table.unpack(libs))
end
local turtle-tracker = require(libDir .. "turtle-tracker")
-- Use the library
local turtleApi = require("turtleApi")
-- Configure the API endpoint
turtleApi.setEndpoint("http://localhost:3000")
-- Initialize with turtle ID (defaults to os.getComputerID())
turtleApi.init()
-- Update stats
turtleApi.incrementStat("blocks_mined")
turtleApi.incrementStat("debris_found", 5)
-- Update position
turtleApi.setAbsolutePosition(100, 64, -200)
turtleApi.setRelativePosition(5, 0, 10)
-- Push data to server
turtleApi.sync()
-- Or use auto-sync (syncs every N seconds)
turtleApi.startAutoSync(30)module.setEndpoint(endpoint)Set the API endpoint URL
endpoint (string): The base URL of the turtle API (e.g., "http://localhost:3000")module.getEndpoint()Get the current API endpoint
module.init(id, label)Initialize the turtle API client
id (string|number|nil): Optional turtle ID (defaults to os.getComputerID())label (string|nil): Optional turtle label (defaults to os.getComputerLabel())module.setDefault(stats)Set default stats (similar to CC state.setDefault pattern)
stats (table): Default stat valuesmodule.getStats()Get the current stats
module.getStat(statName)Get a specific stat value
statName (string): Name of the statmodule.setStat(statName, value)Set a specific stat value
statName (string): Name of the statvalue (number): The value to setmodule.incrementStat(statName, amount)Increment a stat by a value (default 1)
statName (string): Name of the stat to incrementamount (number|nil): Amount to increment by (default 1)module.decrementStat(statName, amount)Decrement a stat by a value (default 1)
statName (string): Name of the stat to decrementamount (number|nil): Amount to decrement by (default 1)module.setAbsolutePosition(x, y, z)Set the absolute position (world coordinates)
x (number): X coordinatey (number): Y coordinatez (number): Z coordinatemodule.getAbsolutePosition()Get the absolute position
module.setRelativePosition(x, y, z)Set the relative position (from starting point)
x (number): X offsety (number): Y offsetz (number): Z offsetmodule.getRelativePosition()Get the relative position
module.moveRelative(dx, dy, dz)Update relative position by offset
dx (number): X offset to adddy (number): Y offset to adddz (number): Z offset to addmodule.moveAbsolute(dx, dy, dz)Update absolute position by offset
dx (number): X offset to adddy (number): Y offset to adddz (number): Z offset to addmodule.setLabel(label)Set the turtle label
label (string): The label to setmodule.setFuel(fuel)Set fuel level manually
fuel (number): The fuel levelmodule.getFuel()Get the current fuel level
module.buildPayload()Build the full data payload for syncing
module.sync()Sync all turtle data to the server
module.syncStats()Sync only stats to the server
module.syncPosition()Sync only position to the server
module.fetch()Fetch turtle data from the server
module.fetchAll()Fetch all turtles from the server
module.delete()Delete the current turtle from the server
module.deleteById(id)Delete a specific turtle by ID from the server
id (string|number): The turtle ID to deletemodule.startAutoSync(intervalSeconds)Start automatic syncing at a given interval
intervalSeconds (number): Seconds between syncs (default 30)module.isAutoSyncRunning()Check if auto-sync is running
module.forward()Wrapper for turtle.forward() that updates relative position
module.back()Wrapper for turtle.back() that updates relative position
module.up()Wrapper for turtle.up() that updates relative position
module.down()Wrapper for turtle.down() that updates relative position
module.dig()Wrapper for turtle.dig() that increments blocks_mined stat
module.digUp()Wrapper for turtle.digUp() that increments blocks_mined stat
module.digDown()Wrapper for turtle.digDown() that increments blocks_mined stat