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.

CookieOS provides two complementary pieces of chat functionality: a Chat program that lets you type messages from the computer terminal and broadcast them into the Minecraft in-game chat, and a Gemini Chat event handler that runs continuously in the background, watching all in-game messages and responding to any that start with the ., prefix using Google’s Gemini AI.

​
Chat Program

The Chat program lives at os/programs/chat and is launched from the Programs menu. It requires a chatBox peripheral attached to the computer.

​
Prerequisites

A chatBox peripheral must be connected before launching. If none is found, the program prints an error and exits without entering the main loop. In the Programs menu, the “Chat” entry is shown in red text when no chatBox is detected.

​
How It Works

On launch, the program locates the chatBox peripheral with peripheral.find("chatBox"). It then enters a loop that reads a line of input from the terminal with read() and sends any non-empty input to in-game chat as the player Dave using: 
chatB.sendMessage(msg, "Dave", "<>")
The third argument "<>" sets the message prefix displayed in chat. Each send is wrapped in cosUtils.safeRun so that any runtime error triggers a CookieOS BSOD rather than silently dropping the message.

​
Usage

-- After launching from the Programs menu:
-- Type a message and press Enter to send it to in-game chat.
-- The message is sent as player "Dave" with the prefix "<>".

​
Gemini Chat Event Handler

The Gemini integration lives at os/events/geminichat.lua. It is not launched manually — it is auto-loaded as a background coroutine by startup/startEvents.lua when CookieOS boots.

​
How It Works

The handler calls peripheral.find("chatBox") and then enters an infinite loop listening for chat events. Every in-game message received by the chatBox is processed:
  1. The sender’s name and message are logged into a per-player history table (players).
  2. History entries are sorted by os.clock() timestamp, newest first.
  3. If the message begins with .,, the text after those two characters is extracted as a query.
  4. The query and the last 10 messages from all tracked players are passed to cosUtils.Gemini().
  5. The AI response (capped at 600 characters) is sent back into in-game chat as Davey with the <> prefix.

​
Trigger Pattern

-- In-game, any player can type:
-- .,What is Create mod?
-- Davey will respond in chat.

-- Special diagnostic command:
-- !tblsize  -- prints the size of the entire chat history table in bytes,
--           -- broken down per player, and also for Davey's own response history.

​
AI Persona

Davey is configured via a system instruction embedded in cosUtils.Gemini:
“Your name is Davey. You’re someone playing on a modded Minecraft server, and you’re an expert with Create, CC:Tweaked, Mekanism, Powah, Mystical Agriculture and much more. You’re also knowledgeable about programming, and things outside Minecraft. Please be concise in your responses.”
Davey’s own responses are stored under the key "gem" in the players history table, and are labelled "Davey" when passed back to the API as conversation history, so the model receives full multi-turn context.

​
Configuring the Gemini API Key

The API key is defined inside cosUtils.Gemini in apis/cUtils.lua. You must replace the placeholder before the feature will work: 
-- In apis/cUtils.lua, cosUtils.Gemini function:
local geminiApiKey = "YOUR_GEMINI_API_KEY" -- Replace this
-- Uses model: gemini-1.5-flash-latest
-- Max output tokens: 250, Temperature: 0.7
1

Open apis/cUtils.lua in the editor

From the File Explorer or shell, open apis/cUtils.lua.
2

Locate the cosUtils.Gemini function

Search for the line local geminiApiKey = "YOUR_GEMINI_API_KEY" near the bottom of the file.
3

Replace the placeholder

Replace "YOUR_GEMINI_API_KEY" with your actual key obtained from Google AI Studio.
4

Save and reboot

Save the file and reboot CookieOS. The Gemini handler will pick up the new key on next startup.
If geminiApiKey is left as "YOUR_GEMINI_API_KEY", cosUtils.Gemini returns nil and an error string immediately without making any HTTP request. Davey will not respond to any ., queries until a valid key is set.
geminichat.lua is auto-loaded because startup/startEvents.lua iterates over every .lua file in the os/events/ directory and runs each one as a background handler via parallel.waitForAny. You can add your own background event handlers to that directory and they will be loaded automatically on the next boot — no changes to startup files required.

Build docs developers (and LLMs) love

Get started for freeTalk to us