Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/PrinceOfCookies/CookieOS/llms.txt

Use this file to discover all available pages before exploring further.

The UI helpers in cosUtils cover everything needed to build a polished CookieOS interface: clearing and resetting windows, drawing bordered boxes with CC:Tweaked box-drawing characters, printing centered text, rendering boxed menus with optional slow-print animation, displaying the top menu bar, animated loading bars, the blue-screen-of-death error display, safe function execution, color interpolation, monitor slow-print, flashing text, and a full touch-driven on-screen keyboard for attached monitors.

​
cosUtils.resetScreen(win)

Clears the given window, moves the cursor to position (1, 1), and resets colours to white text on a black background. Call this before drawing any new screen to ensure a clean slate.
​
win
window | term
A CC:Tweaked window object or term (the main terminal).
cosUtils.resetScreen(term)
-- Screen is now clear, cursor at (1,1), white-on-black

​
cosUtils.drawBox(win, x, y, width, height, fgColor, bgColor)

Draws a bordered rectangle using CC:Tweaked box-drawing characters. The box has a top border, bottom border, and left/right vertical bars. The top-right corner uses a colour-swap trick to achieve a two-tone shadow effect.
​
win
window | term
The window or terminal to draw on.
​
x
number
Left edge of the inner content area (the box border is drawn one column to the left).
​
y
number
Top edge of the inner content area (the box border is drawn one row above).
​
width
number
Width of the inner content area in characters.
​
height
number
Height of the inner content area in rows.
​
fgColor
color
default:"colors.white"
Foreground (border line) colour. Defaults to colors.white.
​
bgColor
color
default:"colors.black"
Background colour inside the box. Defaults to colors.black.
cosUtils.drawBox(term, 3, 3, 20, 5, colors.cyan, colors.black)
-- Draws a cyan-bordered 20×5 box at column 3, row 3

​
cosUtils.centerPrint(yPos, w, text, col, win)

Prints a string centred horizontally at a specified row. The horizontal position is computed as floor((w - #text) / 2).
​
yPos
number
The row at which to print the text.
​
w
number
The width of the screen or window (used for centring calculation).
​
text
string
The string to print.
​
col
color
default:"colors.black"
Background colour for the printed text. Defaults to colors.black.
​
win
window | term
default:"term"
The window to print to. Defaults to term.
local w, h = term.getSize()
cosUtils.centerPrint(math.floor(h / 2), w, "Welcome to CookieOS")

​
cosUtils.centerPrintTable(y, w, items, numOp, slowPrint, backgroundColor, boxmargins, window, textColors)

Draws a centred, boxed menu from a table of strings. The function calculates the longest line to determine box dimensions, draws the outer box via cosUtils.drawBox(), then prints each item centred inside. Per-item text colours are supported via textColors.
​
y
number
The starting row of the box.
​
w
number
Screen or window width, used for horizontal centring.
​
items
table
Ordered table of strings. Empty strings "" act as blank spacer rows.
​
numOp
number
default:"0"
Index of the currently selected item. The caller is responsible for highlighting the selected entry (e.g. by wrapping the text in brackets before passing to this function).
​
slowPrint
boolean
default:"false"
If true, each item is written with textutils.slowWrite at speed 9 for a typewriter effect.
​
backgroundColor
color
default:"colors.black"
Background colour applied to all menu items.
​
boxmargins
boolean
default:"true"
If true, adds 4-character horizontal padding and 2-row vertical padding around the menu items inside the box.
​
window
window | term
default:"term"
The window to draw on.
​
textColors
table
default:"{}"
Optional table of colors.* values indexed by item position. Items without an entry default to colors.white.
local w, h = term.getSize()
local items = {"", "Main Menu", "", "[ Option 1 ]", "Option 2", "Option 3"}
cosUtils.centerPrintTable(
    math.floor(h / 2) / 2,  -- y position
    w,                        -- screen width
    items,
    selectedIndex,
    false,                    -- no slow print
    colors.black,             -- background
    true,                     -- box margins
    term                      -- window
)

​
cosUtils.drawMenu(device)

Draws the CookieOS top bar: the version string (cosv) in yellow on the left and the current time in HH:MM AM/PM format on the right. Rendering is done into an internal off-screen drawMenuWin window and then made visible in a single step, preventing flicker. The bar always occupies row 1 and spans the full terminal width.
​
device
window | term
Accepted for convention — the function uses the internal drawMenuWin window regardless of the value passed. Pass term as the conventional argument.
-- Typically called in a loop or on a timer event to keep the clock live
cosUtils.drawMenu(term)

​
cosUtils.menuKeyUpDownManagement(key, num, max, min)

Handles Up/Down arrow-key navigation for menus with wrap-around at both ends. Pass the raw key value from os.pullEvent("key") and the current selected index; the function returns the updated index.
​
key
number
The key code received from os.pullEvent("key"). The function checks for keys.up and keys.down.
​
num
number
The current selected index.
​
max
number
The maximum valid index. When num == max and Down is pressed, wraps to min.
​
min
number
The minimum valid index. When num == min and Up is pressed, wraps to max.
Returns the updated index as a number. 
local numOp = 1
while true do
    -- redraw menu ...
    local _, key = os.pullEvent("key")
    numOp = cosUtils.menuKeyUpDownManagement(key, numOp, 5, 1)
end

​
cosUtils.loadingBar(device, y, col)

Draws an animated loading bar that fills from right to left across 10 characters. The total animation duration is proportional to cosUtils.fileCount(""), so the bar takes longer on computers with more files — visually reflecting the OS boot workload. A percentage counter is shown in the centre of the bar as it animates.
​
device
window | term
The terminal or window to draw on. device.getSize() is called to centre the bar.
​
y
number
The vertical row at which the bar is rendered.
​
col
color
The fill colour of the loading bar.
cosUtils.loadingBar(term, 10, colors.green)
-- Draws and animates a green loading bar on row 10

​
cosUtils.BSOD(err, device)

Displays a blue screen of death. The error message is uppercased and spaces are replaced with underscores. Five random memory addresses (via the module-local RMA() function) are generated for the STOP: technical information line. After the user presses any key, the error is logged to OS.log via cosUtils.logToOS() and the computer reboots.
​
err
string
The error message to display. Will be transformed to UPPER_SNAKE_CASE on screen.
​
device
window | term
The terminal to draw the blue screen on.
cosUtils.BSOD("Something went terribly wrong", term)
-- Shows blue screen, logs error, waits for keypress, then reboots
Use cosUtils.safeRun() to automatically invoke the BSOD on any unhandled error rather than calling cosUtils.BSOD() directly.

​
cosUtils.safeRun(func, …)

Wraps a function call in pcall. If the function throws an error, cosUtils.BSOD(err, term) is called automatically. This is the recommended way to run top-level program logic in CookieOS applications. Returns status (boolean), err (string | nil).
​
func
function
The function to execute inside pcall.
​
...
any
Any additional arguments are forwarded to func.
cosUtils.safeRun(function()
    -- code that might error
    local f = fs.open("/nonexistent", "r")
    f.readAll() -- would error
end)
-- If error occurs: BSOD is shown instead of crashing

​
cosUtils.waterMark(win)

Prints the cosv global (the CookieOS version string) in yellow on the given window, then resets the text colour to white.
​
win
window | term
default:"term"
The window to print the watermark on. Defaults to term.
cosUtils.waterMark(term)
-- Prints e.g. "CookieOS v2.2.5" in yellow at the current cursor position

​
cosUtils.goodByeSetup(device)

Centres the cursor on the screen and resets colours to white-on-black. Called internally by the overridden os.reboot() and os.shutdown() before printing “Goodbye”. You can call it directly before any graceful exit.
​
device
window | term
The terminal whose size is used to compute the centre position.
cosUtils.goodByeSetup(term)
os.reboot()

​
cosUtils.colorLerp(startColor, endColor, speed)

Linearly interpolates between two RGB colour tables. The speed value is clamped to 1.0 so the result never overshoots endColor.
​
startColor
table
An {r, g, b} table where each component is in your chosen range (e.g. 0–255).
​
endColor
table
Target {r, g, b} table.
​
speed
number
Interpolation factor from 0.0 (fully at startColor) to 1.0 (fully at endColor). Values above 1.0 are clamped to 1.0.
Returns a new {r, g, b} table. 
local start = {255, 0, 0}   -- red
local finish = {0, 0, 255}  -- blue
local mid = cosUtils.colorLerp(start, finish, 0.5)
print(mid[1], mid[2], mid[3]) -- 127.5  0.0  127.5

​
cosUtils.monSlowPrint(txt, delay)

Writes a string to an attached monitor peripheral one character at a time, pausing delay seconds between each character. Errors with assert if no monitor is found.
​
txt
string
The text to print character by character.
​
delay
number
default:"0.3"
Seconds to wait between each character. Defaults to 0.3.
cosUtils.monSlowPrint("Hello, world!", 0.1)
-- Requires an attached monitor

​
cosUtils.textFlash(x, y, text, delay)

Repeatedly writes text at position (x, y) and then clears it, creating a blinking effect. If a monitor is attached, it flashes on the monitor; otherwise it flashes on term. The function runs an infinite loop and should be executed inside a coroutine or via parallel.waitForAny.
​
x
number
Horizontal cursor position for the text.
​
y
number
Vertical cursor position for the text.
​
text
string
The string to flash.
​
delay
number
default:"0.3"
Seconds between write and clear operations. Defaults to 0.3.
-- Run in parallel so the rest of the program can continue
parallel.waitForAny(
    function() cosUtils.textFlash(5, 5, "LOADING...", 0.5) end,
    function()
        os.sleep(5) -- stop after 5 seconds
    end
)

​
cosUtils.onScreenKeyboard()

Displays a colour-coded QWERTY keyboard layout on an attached monitor. The user interacts with it via monitor_touch events. The keyboard supports Shift (toggles case for all keys), Backspace (deletes the last character), Space, and Enter (finishes input and exits the loop). Each key is rendered with a random foreground/background colour pair for a distinctive look. Returns the typed string when Enter is pressed.
This function requires a monitor peripheral. It calls assert and errors if none is found.
local mon = cosUtils.isMonitorHere()
if mon then
    local typed = cosUtils.onScreenKeyboard()
    print("You typed: " .. typed)
end

Build docs developers (and LLMs) love

Get started for freeTalk to us