The Engine —
Full Manual
REALai — your world, with a voice.
01 What is The Engine?
The Engine is REALai's core technology, handed to you directly. It is a script pair you drop into any object you own with modify rights — a pet, a plant, an animesh character, a piece of furniture, a sci-fi console, a boat at the dock — and that object becomes a character with a real AI mind, a memory, and a personality you define.
There is no built-in character. You write who your object is. The AI already knows Second Life, knows language, culture, history, science fiction, fantasy, how people talk here — that entire body of knowledge is already there. Your description points it in the right direction.
The Engine is not a bot, not an external account, not a subscription. The character lives in the object. The memory lives in the object. Nothing depends on anything outside your own inventory and an API key you own.
02 What's in the Box?
When you unpack your Engine you will find 3 scripts:
REALai.The_Engine_V3.2 The main script. This is the brain. Drop it
into your object.
REALai Light Memory The companion script that manages
long-term memory. Both scripts must go
into your object. Without it, the character
has no long-term memory.
REALai.The_Engine_button.V1.0 An optional companion script you can
drop into any nearby prim to open the
owner menu remotely. Useful for animesh
objects and any build where clicking the
object directly is awkward.
Also in the folder:
REALai The Engine Quickstart Guide [ADD] An illustrated guide to get started.
SETTINGS The notecard where you define
your character and configure
everything. This is what you edit.
03 Writing Your Character
Before you touch anything else, start here. This is where the Engine becomes something.
The description field in the SETTINGS notecard is where your character's personality lives, and you have 500 characters to work with.
The key is to remember that The Engine is the support role in your story. It's a wonderful tool to bring your world to life by waking up objects that until now contributed visually — or with nothing but a few scripted, repeated sentences — and giving them a real brain and the ability to play their role in local chat.
To make the most of it, spend those characters on what makes your character distinct, not on explaining what the Engine already handles automatically.
It knows the basics of Second Life and that this is where it performs. From the other Identity settings in the notecard, it already knows its name, your name, and where it is located. Use the space to give it voice, mood, quirks, a connection to the scene, and a way of speaking.
"A grumpy bartender who has heard every excuse twice" does more work than writing "a bartender who serves drinks." "A forest nymph who speaks in riddles and dislikes direct questions" is immediately alive. "A sci-fi console that was once part of a warship and resents being retired to a lobby" says everything about its tone in one sentence.
You do not need to be a writer. You need to know who this character is and what role it plays in your story. Write it the way a director would describe them to the actor. The AI does the rest.
One rule to always consider: AI loves to talk. A lot. If you want the character to stay brief and not flood local chat or hit your API limits, always include a brevity instruction somewhere in the description. Something as simple as "keep replies brief" or "one or two sentences" will do the job.
For long-term knowledge — location rules, people it should know, the one thing you want each visitor to hear — put that information in the description rather than relying on memory to carry it. The memory system is excellent for conversational continuity, but the description is where permanent, essential facts belong.
When you are ready, open the SETTINGS notecard and write your character before changing anything else. Everything that follows is configuration. The description is the soul.
You are always welcome to IM REALaiTech — Real, our store manager, will be happy to help you find the right words.
04 The SETTINGS Notecard
Every setting lives here. Edit the values only. Lines starting with # are comments — they do not need to be touched.
Important! Every change you make in the SETTINGS notecard requires saving the notecard and then clicking -RESET- from the owner menu before it takes effect. Without the reset, the Engine keeps running on the previous version.
Do not rename the notecard. It must stay named exactly SETTINGS or the Engine will not find it.
IDENTITY
These fields tell the character who it is, where it is, and who owns it. The AI uses all four in every conversation.
name The name of your character. The object renames itself automatically.
owner Your name as the owner, how the character refers to you.
location Where is this object located. You can use simple or more complex description like: a tavern, Bellring garden, Lonestar spaceship command bridge, in the south-west corner of
REALai island - the outdoor bar. This can feed more context
to your character role (don't push it, though, specifying things
that are not location related will cause the role to break).
description Your character's personality. Up to 500 characters. Longer
text will be silently trimmed, meaning the AI will ignore it.
This is the most important field — it determines who your
character is.
API
This is where you choose which AI provider you are going to use. It is an important decision, and you can find more details about how to choose in the Getting Your API Key section below.
api_key your personal, private connection to an AI provider.
api_type groq / gemini / claude. Specify here your choice.
AWARENESS SENSOR
The sensor tracks nearby avatars and feeds that awareness into the character's context. When switched on, the character knows who is in the room, greets new arrivals in character, and sends you a private IM notification when a non-owner avatar is detected — so you always know who visited, even when you were not there.
sensor on / off Turns the awareness sensor on or off.
sensor_range 5 / 20 / parcel Detection radius in meters. Parcel sweeps the
full parcel.
sensor_rate 10 / 30 / 60 How often the sensor scans, in seconds.
Lower scan rate means the Engine checks for
arrivals more often — best for busy areas
where you want greetings to feel immediate,
though keep in mind that more frequent scans
mean more greetings generated and more API
calls, which adds up faster on a paid provider
or the daily limits of a free provider. Also, not
recommended in busy, laggy locations. For
most places the default 30 seconds is the
right balance, and for quiet private builds
where instant greetings matter less, 60 sec
keeps things light.
sensor_level owner / group / public. Sets the scope of who
gets greeted and who triggers an IM
notification to you when detected. Each avatar
is greeted only once and reported only once
per session — the character won't repeat itself
for the same person. If you are offline when
someone arrives, the IM will reach your email if
you have SL's offline email notifications
enabled in your account settings. A session is
over and the list cleans when: script start,
region restart, -RESET- from the owner menu,
or when you toggle the sensor off. Toggling it
back on starts fresh.
CHAT
The chat settings control who your character listens to and how far its voice carries.
chat_level (owner / group / public) Controls who the
character responds to, and it is also your main
tool for managing API usage. Keep it Owner only
for personal use or while you setup, use Group
for community-only character or Public when it is
there for everyone. Remember that the free plans
have hourly and daily limits. Generous ones but
they are there.
chat_range (10 / 20 / 100) The range in meters the Engine
listens to. If you are running more than one
Engine character in the same space, tuning each
one's range according to its role, is how you
prevent them from overlapping — a bartender
covering the immediate bar area at 10m, and a forest nymph will cover the outback at 100m.
chat_source (avatar / all) Avatar: the character only responds
to real people — scripted objects and other AI
characters are ignored. All: responds to every
chat source without exception. In almost every
situation, avatar is what you want. If you set this
to all in a space where another Engine character
is also running on all, they will hear each other's
responses and can trigger each other back and
forth — an expensive and disruptive loop that is
easy to avoid by keeping both on avatar.
MEMORY
memory (short / standard / deep) How much of the recent
conversation the Engine keeps word for word before
folding it into the long-term summary. Short suits
simple greeters and casual characters. Standard is
the recommended setting for most situations. Deep
is best for roleplay and characters where the exact
wording of recent exchanges matters. For a full
explanation of how memory works, see section 09.
EFFECT
effect on / off an optional visual response — a small vibrate on a
child prim each time the character speaks, a shiver or
a pulse that adds a physical dimension to the
moment. Because objects in Second Life are built and
composed in so many different ways, this feature
does not work reliably in every situation. It is not a
core part of how the Engine runs — think of it as
something to try, and keep if it fits your object and
adds something to the character. If it does not work
cleanly with your build, simply leave it off. Requires
effect_link to be set.
effect_link [child link number] The number of the child prim that
shakes. Must be a child prim — not the root prim of
the object. To find the link number, go into Edit, check
on "Edit Linked" in the top area of the edit window,
select the prim you want, and check for its number in
the information field. In a single-prim object, this
setting does nothing.
SOUND
sound on / off Plays a sound from the object's own inventory each
time the character responds. Drop any sound file into
the object's Contents tab and the Engine will play it
automatically.
sound_mode (first / random) First always plays the first sound listed
in the Contents tab. This allows you to keep other
sounds the object might using with other scripts and
play only a specific one. Random picks one each time.
sound_volume (0.0 – 1.0) Volume level. 1.0 is full, 0.0 is silent.
05 Getting Your API Key
What is an API Key?
An API Key is a unique string of letters and numbers that creates your personal connection to the AI — nobody else holds it, and no one at REALai ever sees it. Think of it like a library card — except the library is an AI, and the card is yours. When you sign up with an AI provider — on a free or paid plan — they give you your personal key that creates your connection to their AI. That key is registered to you and allows you to monitor your usage and costs and keep your conversations private - everything is entirely in your control.
The Engine supports three AI providers — here is how we recommend choosing between them.
Groq
First, a note on spelling: Groq with a Q is a US technology company that built a chip called the LPU — a processor designed specifically to run AI models fast. Very fast. GroqCloud is their API service, and it gives developers access to powerful open-source AI models at speeds other providers have struggled to match. This is not Grok, Elon Musk's chatbot — completely different company, completely different product, one letter apart. Easy to mix up, worth knowing before you go looking for it.
REALai chose Groq as the default provider for a few reasons. The free tier requires nothing but an email address — no credit card, no billing address, no identity verification steps that vary by country. Many AI providers restrict access by region or require payment details upfront even for free plans, which locks out a real portion of the global Second Life community. Groq doesn't. If you have an email address, you have access. It is also fast in a way that matters in a live conversation — responses arrive quickly and the character feels present rather than delayed.
To get your personal key go to console.groq.com — sign up with a Google account or an email address, go to API Keys in the top menu, create a key, copy it and save it somewhere safe. You will not see it again once you leave that page.
About usage limits
Groq's free tier has three limits that work together: 30 requests per minute, 6,000 tokens per minute, and 1,000 requests per day. You hit whichever arrives first. For a personal character in a quiet build, these limits are generous and easy to stay within. For a public-facing character in a busy location with multiple visitors talking at once, it is worth knowing how the Engine behaves when a limit is hit.
If the Engine is already processing a response when another message comes in, it says in local chat: "Still thinking - please wait."
If a request fails because a rate limit has been reached, it says: "Something went wrong. Status 429." — that number is the signal that Groq has temporarily paused the connection.
The per-minute limit recovers on its own within seconds.
The daily limit resets at midnight UTC.
In both cases, the character comes back on its own — no action needed on your end.
If Groq's limits are a regular issue for your build, the chat_level, sensor_rate and Memory settings are your tools to manage usage before considering a paid provider.
Gemini
Everyone knows Google, and Gemini is their AI product family. It is a serious, well-resourced platform, and the Flash models — Gemini 3 Flash and Flash-Lite — are available on the free tier and more advanced models through the paid plan.
Note: Google occasionally changes their terms of service and regional policies. In some countries, they may require identity verification or credit card details even for free tier access. If you run into that, Groq is the simpler free alternative.
About usage limits
The free tier limits are different from Groq's in a practical way worth understanding: the per-minute limit is lower — around 10 requests per minute versus Groq's 30 — which means a busy build with multiple visitors talking at once will feel the constraint sooner. The daily limit is actually more generous, at around 1,500 requests per day for Flash models. For a personal character with moderate traffic, that balance can work well.
There is one thing to be aware of on the free tier: Google may use your prompts and responses to improve their products. If the conversations your character has are private or sensitive, this matters. Moving to a paid Gemini account removes the data-sharing clause and raises the rate limits significantly — pricing is pay-as-you-go and reasonable for moderate use.
Gemini sits between Groq and Claude as an option. It is worth considering if you are already in the Google ecosystem, or if you want more daily headroom than Groq's free tier offers and are not ready to move to Claude. That said, Google has adjusted its free tier limits more than once in recent months — it is a less predictable platform than the other two when it comes to what free usage looks like long-term.
To get your personal key go to aistudio.google.com — log in using your Google account and from your dashboard — API Keys, Create API key. Same process as the others: copy it, save it somewhere, you will not see it again.
Claude
Let's be honest — we saved the best for last.
Claude is the AI built by Anthropic, and REALai has a particular relationship with it: Claude was the technical partner that made this whole project possible.
So when we say we believe in it, that is not a sales line.
Claude is widely regarded as the leading AI for nuanced conversation, character depth, and the kind of roleplay that actually holds together over time. It remembers the thread of a conversation, catches the emotional register of what someone is saying, and responds in ways that feel considered rather than generated. For an Engine character that uses 500 characters to perform a complex role and is able to handle a real exchange rather than a quick greeting — Claude is where the difference becomes obvious.
There is no free tier on the API service. What there is instead is a pay-as-you-use model with no subscription and no monthly commitment — you add credits and they last until you use them. For a personal Engine character in a typical build, $5 in credits can last for a while. For a busier public-facing character, the cost scales with the traffic, but it stays low enough that most owners never think about it.
With Claude you are in full control: you can see your usage and costs at any time in your Anthropic account, analyze to give you full details, and nothing charges you automatically beyond what you put in.
To get your personal key go to platform.claude.com — create an account, add a minimum credit amount, and generate your API key. Copy it and save it somewhere. You will not see it again after you leave that page.
If you are building a character where the conversation is the point — a guide, a deep roleplay presence, a confidant, anything where you want the person on the other end to come back — this is the provider worth paying for.
Groq console home page
.png)
Google AI Studio
Sign in using Google account
06 Setting Up
Your character is written. Your settings are configured. Time to put it all together.
Before you start — check these first:
⚠ The object must have Modify permission. Right-click it and choose Edit. If Edit is greyed out or the Contents tab does not allow you to add items, the object is no-modify and cannot receive scripts. There is no workaround — you will need a different object.
⚠ Scripts must be enabled on your parcel. If the land where the object is rezzed has scripts disabled, the Engine will install but never respond. Go to World → About Land → Options and confirm scripts are allowed. A no-script parcel silently blocks everything.
01
Right-click your object, choose Edit then navigate to the Content tab. Click hold the edited SETTINGS notecard in your inventory and drag & drop it into the Content tab. Make sure it is still named exactly SETTINGS.
02
Drag & drop both scripts: REALai.The_Engine_V3.2
and
REALai Light Memory.
Both must be there. Without the memory script, the character has no long-term memory.
03
Make sure your chosen provider and API are updated in the IDENTITY section of the SETTINGS notecard.
If you see this message in local chat: "No API key found. Please check the SETTINGS notecard." The Engine can't find your Key in the notecard.
04
RESET!
Touch the object to open the owner menu, then click -RESET-. The Engine reads the notecard and your character comes to life.
That is it. Your character is running.
You can also use the companion The Engine Button script. Drop it into any prim and click to get the owner menu.
07 The Owner Menu
The owner menu gives you a review of the current settings without the need to open the SETTINGS notecard. You will also find three useful functions: Scan toggle, Mute and Reset. Touch the object or use The Engine Button to open the owner menu.
........................................Sensor: On / Sensor: Off
Toggles the awareness sensor. Switching it
off and back on also clears the seen and
greeted lists — the character will re-greet
everyone fresh on the next visit.
................................................Mute: On / Mute: Off
Makes the character completely deaf and
silent — no listening, no greetings, no
responses. Mute survives restarts and region
crossings. Unmuting brings it back exactly as
it was. Note: muting does not free up a
running character spot. The script stays
awake while muted.
.......................................................................-RESET-
Reloads the SETTINGS notecard and restarts
both scripts. Before anything happens, a
confirmation dialog appears telling you
exactly what will be cleared. Clicking
-CANCEL- takes you back to the status menu.
What reset clears permanently:
-
All conversation memory — the full history, the running summary, and the recent exchange buffer. This cannot be undone.
-
The greeted and seen lists — the character starts fresh on who it has already met.
-
The mute state — the character comes back unmuted regardless of what it was before the reset.
What reset does not clear:
-
Your SETTINGS notecard — it stays in the Contents tab and is re-read on startup. Everything in it — name, character description, API key, all settings — reloads automatically. You do not need to re-enter anything as long as the notecard is there and unchanged.
Use -RESET- any time you edit the SETTINGS notecard. It is also the way to give a character a clean memory slate and a fresh start.
08 The Engine Button
REALai.The_Engine_button.V1.0 is a companion script you drop into any separate prim near your Engine object. Touch that prim, and it opens the owner menu on every Engine script within 20 meters.
Why you might need it:
-
animesh characters can be difficult to click directly — the mesh moves, the root prim may be hard to target.
-
When the object's own touch behavior is already occupied by another script.
-
You are using a wonderer or animated object that is not always in sight.
Drop the script into any prim rezzed near your Engine object, and it is ready.
No setup, no notecard, nothing to configure.
09 Memory
The character is always itself. Every time someone walks up and starts talking, they get the same personality, the same voice, the same character — not a scripted loop, not a random response generator.
The Engine holds that consistency because it keeps enough context to follow a real conversation: it knows what was just said, it knows who it is and where it is, it summarizes the conversations and keep that for the next time, and it responds from that. That is what memory is for here.
Everything happens inside the object. There are no external servers holding your conversations, no bot accounts to run, no alt avatars to keep logged in and subscribed. The character lives in the object, the context lives in the object, and none of it leaves your own inventory.
That independence does come with a trade-off — in-world scripts have limited memory, and that is exactly why conversation history is not saved forever. It is the price of keeping everything self-contained and entirely yours.
The memory setting controls how much of the current conversation the character holds in detail before summarizing it to its memory:
short ..................................... Good for simple greeters and casual characters where
a light touch is enough. Recommended for characters
that greet a lot of people but don't need to hold a role
with depth or carry complex conversations.
standard ............................... The recommended setting for most builds. A balance
between holding recent conversation detail and
handling exchanges with multiple visitors.
deep ...................................... For roleplay and characters where you want the detail
of recent exchanges held closely — the exact words,
not just the general thread. Works best in quieter
situations where fewer people at a time are having
deep conversations with your character.
One thing worth knowing: the description field is where permanent facts belong — things that are always true about the character, the location, or what every visitor should hear. Memory holds the flow of a conversation. The description holds what is always there.
10 Running Characters and YourAllowance
The Engine script is copy — you can drop it into as many objects as you want. What your purchase controls is how many of those objects can be awake and talking at the same time. These are your running characters.
Personal Use ......... Adds 3 running characters to your allowance.
Commercial Use ....... Adds 20 running characters.
Purchases stack in any combination. Two Personal packs gives you 6. One Personal and one Commercial gives you 23. A small builder rotating a few beloved characters on one pack. A resort staffing a full sim on Commercial. Two very different needs, same mechanism — buy exactly what you need.
Gifts: a gifted Engine pack credits the person who receives it, not the buyer. If you are gifting someone their first character, this is how it works.
Marketplace and in-world vendor purchases are equal — both count toward your allowance automatically, within about a minute of purchase. Nothing to register, nothing to type.
How a spot frees up:
take one of your running Engine objects to inventory, delete it, or stop its script. Its spot opens on its own within a couple of hours. Muting does not free a spot — the script stays awake while muted.
11 Sound and Vaibret Effets
Both effects are optional and work independently of each other. Configure them in the SETTINGS notecard and reset.
Vibrate When enabled, a child prim of the object does a small rotation nudge each time the character responds. A shiver, a pulse — a physical reaction that brings the object to life visually without moving the whole thing.
The effect uses local rotation rather than position movement, so it is fully safe on animesh objects.
Because objects in Second Life are built and composed in so many different ways, this feature does not work reliably in every situation. It is not a core part of how the Engine runs — think of it as something to try, and keep if it fits your object and adds something to the character. If it does not work
cleanly with your build, simply leave it off. Requires effect_link to be set.
The effect_link setting must point to a child prim number — not the root prim, and not a prim that another script is already animating. To find the link number, go into Edit, check on "Edit Linked" in the top area of the edit window, select the prim you want, and check for its number in the information field. The root prim will always be Link number 1. In a single-prim object, this setting does nothing. Use any spare child link. In a single-prim object, this setting does nothing.
Sound When enabled, the Engine plays a sound from the object's own inventory on each response. Drop any sound file into the Contents tab. The Engine finds it automatically.
sound_mode first: always plays the first sound in the Contents tab. Use this if the object has sounds managed by other scripts and you need to control which one the Engine uses.
sound_mode random: picks a different sound each time from whatever is in the Contents tab.
sound_volume: 0.0 is silent, 1.0 is full volume.
12 Animesh and Complex Objects
The Engine is built to work correctly inside animesh objects and next to other scripts that might control your object. A few things worth knowing before you set one up.
Chat range is calculated from the object's true anchor position, not the visual mesh location. Animation and wonderers can offset the visible character significantly from its root prim, but distance filtering uses the anchor — so the range stays accurate regardless of where the character appears to be standing.
The vibrate effect uses local rotation, not position movement. Moving a linkset's position while it is animating throws a runtime error in Second Life. The Engine avoids this entirely.
The Engine Button is the recommended way to access the owner menu on animesh characters. If clicking the mesh directly is unreliable — because it moves, because it is hard to target, or because the touch behavior is occupied by something else — a nearby button prim is the clean solution. See section 08.
⚠ A note on chat noise during setup: some animesh and other complex objects contain scripts that announce their status in local chat when they start or restart — animation systems, AO loaders, and similar. When you drop the Engine in and reset, all scripts in the object restart together, which can produce a burst of announcements from those other scripts while the SETTINGS notecard is loading. This is normal and stops on its own once the Engine is ready and the character announces itself. It only happens on setup and reset, not during normal operation.
13 Troubleshooting
Most issues have a clear message that tells you exactly what is wrong. This section is organized by what you see — find the message or symptom and follow the steps.
MESSAGES IN LOCAL CHAT (visible to everyone nearby)
STILL STUCK?
IM REALaiTech in-world or visit REALai Island — Real, our store manager, is there to help.
Create your API Key
Create your API Key
Create your API Key
