IruMoto NPC Engine for OpenSimulator

The IruMoto NPC Engine is a versatile NPC creation tool for use in virtual worlds running Open Simulator 9 and later.

Purpose and functionality

The IruMoto NPC Engine creates and manages a single NPC (a.k.a. “bot”), with up to 11 appearances, over which you have absolute control.

You don’t need to know how to write scripts, but you will be opening scripts and editing lines here and there. It isn’t terribly complex and I’ve provided pretty comprehensive instructions throughout the scripts and notecards. Don’t be discouraged from giving it a go. If you have a day to play and want to learn something new, I say go for it.

The generated bot ‘sits’ on the engine (except in Guest mode). The bot can operate as its own individual entity, or collectively with other bots when controlled by an external script such as the IruMoto Love Engine or IruMoto Time Generator.

Extremely customisable and comprehensive variables allow the NPCs to be used in-world as models at shops, staff or friends wandering around performing pre-set tasks, or companions, lovers, entertainers etc.

NPCs are capable of any action and also have facial expressions courtesy of the inbuilt PUMP Expressions code.

You may use the IruMoto NPC Engine scripts and notecards for whatever purpose but must retain the commented header sections contained in each script.

Variables

Core variables such as name, gender, menu channel, and sensor channel are managed via the supporting .npcConfig notecard. Several other notecards control the NPC’s appearance as well as profile information and pictures.

All scripts are designed to be ‘set and forget’ with the exception of .[npcAction] which listens for commands from an external script to determine each of the NPC’s actions.

Components

Necessary component parts of the IruMoto NPC Engine are:

Internal components:

External support scripts:

Bot Types

The type of NPC can be set in the .npcConfig notecard. The chosen type determines how it is activated to come online and what functionality it has. Options are:

  • Sensor – an external sensor tells the bot to come online when an avatar arrives. Most commonly used as a ‘greeter’ bot, visitors may or may not interact with it via a blue menu or NPC Love Engine, depending on your settings in .npcConfig. A sensor bot automatically dies to save sim resources when it senses no avatars are in its defined proximity.
  • Trigger – an external script, when activated by an avatar, tells the bot to come online and prepare to perform a menu driven scenario, either with the avatar or other NPCs. Ideal for story telling scenarios, or lover sequences. Trigger bots automatically reboot at intervals set in .npcConfig to keep the bot fresh and glitch-free. Like sensor bots, trigger bots automatically die when no avatars are around.
  • Always – ideal for static NPCs, essentially props with a single animation. Actions can be enhanced by an external script. Always bots automatically reboots at regular intervals that are set in .npcConfig to keep the bot fresh and glitch-free.
  • Guest – a very specific type of trigger bot which you will probably never use. Guest bots allow tenants of a region that you own, to host your bots on their land and use their own commands. Without faffing about, it is basically an escort bot that can visit someone’s private house and use their sex beds etc.
A bot created by an IruMoto NPC Engine performs as a club entertainer
A sensor bot ‘dancer’ created by an IruMoto NPC Engine comes online when an avatar enters the club.

Quirks and Kudos

First, I use the terms “NPC” and “bot” interchangeably. They mean the same thing.

When NPCs first became available in 2013, I was on the InWorldz grid which ran a forked version of Open Simulator. The InWorldz grid monkeys followed their own star and the bot technology they developed was magnificent. That is where my NPC scripting journey began.

I have retained the term “bot” in my scripts, in part for that perhaps-sentimental reason, plus it’s only one syllable 🙂 and finally, to avoid any possible future function clashes as more features are added to the osNPC code library.

Second, the syntax of my file names might look odd, but there is logic behind it.

  • All IruMoto scripts start with a period then a brace;
  • All notecards start with a period but no brace;
  • All animations start with a period then capital X.

This syntax is for the sake of order in my Contents windows. Scripts are always at the top, followed by notecards, followed by animations. It keeps things neat and simple.

Setup

Assemble your tools

  1. In your inventory, make a folder called “IruMoto NPC Engine”. We’ll put everything in a folder before we drag it into a prim because there is a sequence to things.
  2. In this folder, create all the scripts and notecards listed in the components section above.
  3. Add some animations to the folder. Don’t worry about what they are for now – You can change them later. Priority 4 animations will work best, but again, no biggie for now.
  4. Rez a prim. I find a cylinder works best, 1 metre(X) x 1 metre(Y) x 2 metres tall (Z). Make it phantom. Name the prim “NPC500”. You can change this later if you want. In the General tab, click “Copy Keys” or “Copy UUID” depending on your viewer.

.npcConfig notecard

Open the .npcConfig notecard. Follow the instructions precisely. Everything you enter in the notecard is changeable in the future so don’t over-think it for now.

NPC Config notecard for IruMoto NPC Engine
  1. Give your bot a first name and last name and choose its gender.
  2. For #DEFAULT OUTFIT, set this to .outfit1 for now. We will set up your first few outfits in this tutorial and you can add others later. You can change the default outfit later if you want to.
  3. Set #BOT TYPE to SENSOR. This way I can show you how the all-important sensor support script works.
  4. Under the heading # DEFAULT UUID is a 36 character UUID. This is the unique identifier of the prim containing your NPC Engine, which you just copied. Paste the new UUID over the one already in the card. This will link your engine to the bot that it generates. It will also force the bot to sit on the engine, which is how we animate it.
  5. Make up a 7 or 8 digit negative number for #MENU CHANNEL. Must be absolutely unique – No other bots or scripted objects on your region can use this channel.
  6. For #SENSOR CHANNEL, again you need a large negative number, however this number will be shared by any other bots or props you want in the scene, plus the scene sensor itself. I usually just use the date (but negative), e.g. -YYMMDD to make it easy to remember while setting up a scene. A handy habit is to also add the number to the name of your engine in brackets so you can see the channel at a glance just by hovering over the prim at a later date. This saves you having to go into Contents, open the notecard etc.
  7. #TRIGGER WORD – keep it simple, e.g. “Pool” if the scene is by the pool. Again I tend to add this to the prim name. So at this point, the name of my engine might be “NPC500 zac.paluwayo [Pool -210830]”. This contains all the info I need to know at a glance without opening up the contents.
  8. The rest of the headings are self explanatory. Most users won’t need to change them.
  9. Save the .npcConfig notecard, then drop it into the Contents tab of your NPC Engine.

.npcProfile notecard

If you want to populate your NPC’s profile, edit the .npcProfile notecard as per its instructions, then save and drop into your engine. If you don’t want a profile, just drop the notecard in ‘as is’ – The NPC’s profile picture will be blank and its profile will just read “Hi.”

Bot profile notecard for IruMoto NPC Engine

.botOutfits notecard

Open the .botOutfits notecard. Give each outfit a name. Put in anything for now, as long as each name is different, e.g. Red Dress, Blue Dress, Bikinis, etc. Save and drop into engine.

Bot outfits card for IruMoto NPC Engine

Drag and drop files

Drop the following files into your engine untouched:

  1. 11 blank .outfit(?) cards
  2. .[npcEmotions] script
  3. at least 3 animations for now

.[npcAction] script

Main Default

Open the script .[npcAction] . This is the most complex part of setup but it’s pretty easy after the first time and you see how everything interacts.

At line 108: mainDefault(), you will see that the ‘else if’ statement for SENSOR actions a function called ‘startup0()’. This is correct because you stated in .npcConfig that the botType was SENSOR. If at some future point, you change the botType to e.g. TRIGGER, then you have to move the ‘startup0()’ function to the TRIGGER else if statement line.

Animation Sequences

Just below this, you will see a section called ANIMATION SEQUENCES. I have entered 3 sample animations there for you to change.

In each sequence, the line that begins with newA means ‘new animation’, so this is the animation that the NPC will use when this action is called. Enter the name of one of your animations and type over the sample name. Don’t delete the quotation marks or semi colon. Do the same for the other two sample sequences.

The next line, newP means ‘new position’. These are the coordinates on your region that the NPC will move to when the action is called. For now, we will use the position of the engine. To get this info, click on the Object tab. Under the heading ‘Position’ you will see the coordinates. Click on the ‘C’ button to copy them. Paste the coordinates into the newP section for the three sample sequences. Don’t delete the lesser-than and greater-than symbols or semi colon.

The next line, newR means ‘new rotation’. This is the rotation of the NPC on the z axis only, i.e. will it turn left or right and how far. Again, go to the Object tab. Under the heading ‘Rotation’, you are only interested in the value at Z. Enter that number including three decimal places (usually all zeroes). Don’t delete the semi colon.

The next line, newO means ‘new outfit’. This is the appearance that the NPC will take on when this action sequence is called. Since the first sequence is startup0() AND we already determined in the last section that this was the default sequence AND in .npcConfig we stated that .outfit1 was our default outfit, let’s keep it simple and list .outfit1 as the outfit for this particular sequence. For the next two sequences, change the outfit to .outfit2 and .outfit3 in any particular order.

The next line, newE means ‘new emotion’. Sometimes we might want a facial expression to enhance the animation sequence. We’ll leave these as entered for the sake of a quick setup. You can find the full list of available emotions by opening the .[npcEmotions] script at some later point in time. If you don’t want an emotion to play, simply enter “NULL” in that particular sequence.

Finally for this section, with the exception of startup0(), you will see that the labels I’ve given to each animation sequence basically reflect what the animation does. You can enter anything you want as a label but try to keep it under 10 letters and don’t use spaces. For example, your animation might be watching television, so you could name it WatchTV. Whatever you decide, overtype the sample labels to whatever makes sense for you. Remember the labels because we’re about to use them again.

Scroll down to the listen() event at line 158 (this line number will change as you add more animation sequences in the future. You will see a section called Animation calls, and two else if statements containing the sample labels I used above. You need to enter your new labels here, exactly the same as you did in the previous section. So, if you created a label called WatchTV, you would overtype Sunbathe with WatchTV. Don’t delete the quotation marks or brackets. Repeat this for your remaining label.

And that’s it. Save the script and drop it into your NPC Engine. If a script error warning appears on your screen, then you’ve entered something wrong or made a syntax error (usually a deleted quote mark or semi colon). Check the changes you made and try again.

.[npcExist] script

We’re nearly ready. Drop the .[npcExist] script into your NPC Engine.

Did it just turn invisible? Fantastic! Your IruMoto NPC Engine is ready to roll.

If not, then you will have a script error warning on your screen. In this case, it means that you made a mistake on the .npcConfig notecard. This mistake will also affect the .[npcActions] script as both scripts rely on that notecard. Check the notecards in your Contents tab for errors, then click the Reset Scripts button to reload them. Also check what the error message says – It will usually give you a solid clue where the problem lies.

Set up your NPC Sensor

Now rez another prim, nothing fancy, any size, any shape. Name it NPC Sensor, then drop in the .[npcActivateSensor] script.

Open the Contents window then open the script. You will see the sensorChan variable near the top of the page. Change this to the same sensor channel you entered in your .npcConfig card. Don’t forget the minus sign.

Now scroll down and read the commented instructions on tweaking the code. Make changes as you see fit, then save the script and close. That prim is now a sensor and is communicating with your NPC Engine.

As with your engine, I recommend putting the sensor channel in the name of the prim so you can see what it is at a glance.

Test your IruMoto NPC Engine

The first thing we’ll check is the connection between your sensor and engine. Chances are however, that by the time you read this – and assuming you are standing within range of the sensor – a cloud of avatar dust is hovering where your NPC should be. That’s perfect. You’re engine and sensor are working fine. Your NPC doesn’t have any form yet, so let’s fix that.

Remember earlier in the .[npcAction] script, how we entered three different outfits for the three animation sequences you set up? Also, even further back in time, do you remember making up names for your outfits and entering them in your .botOutfits notecard? Well those outfit names will now appear on the menu, allowing us to save some appearances for your NPC.

Saving outfits

This IruMoto NPC Engine works by cloning you, so basically whatever you are wearing at the time you hit the save button, the NPC will also be wearing. It creates a perfect copy.

NOW, super important – remove any HUDs or AOs (animation over-riders) that you are wearing. Your NPC doesn’t need these and they may cause conflicts with the scripts.

Dress yourself how you want you NPC to appear for its default outfit. When you’re ready, left-click the engine and a menu will appear. Choose save, and the Save menu will open, complete with the names of the outfits you specified in the .botOutfits card. Click on the first outfit button. A message will appear in chat telling you the outfit was saved. Now let’s test it.

With the menu still open, click on Main Menu to return to the main screen. Click the Reboot button. This will kill the NPC and make all the scripts re-read all the notecards, including the one the system just saved for your first outfit.

It will also tell the sensor prim that the NPC is offline, so the sensor knows that on the next scan in x amount of seconds, it will rez another NPC. This time however, it should look identical to you.

Your doppelganger should also be doing exactly what you instructed at the startup0() action sequence in the .[npcAction] script. If you’ve done everything right, it should be performing the animation (newA), at the position (newP), on the rotation (newR), wearing the outfit (newO) and with the facial expression (newE).

Assuming that all of that is working fine, go ahead and save another two outfits.

Calls to Action

Now you have three action sequences set up and three outfits, so everything is ready. You can have up to eleven outfits (as per the eleven .outfit notecards in your inventory), and quite a large number of action sequences.

Once your bot is set up, it really is all about the .[npcAction] script. You will find yourself playing with this script quite a lot as your skillset grows and the list of NPC action sequences increases.

To add more action sequences, simply copy and paste one of your existing ones and modify it like you did to my sample ones earlier, and of course, don’t forget to add a corresponding call to action in the listen() event, again as we did earlier.

NPC Action is a super solid script. I don’t know how many action sequences it can handle because I’ve never reached its limit. Some of my NPCs have close to 100 action sequences and they work just fine every time.

Communications

The only thing left to talk about now is communications, i.e. how do you make those action sequences happen? There are several ways. Some require more scripted gadgets to learn, such as the IruMoto Love Engine, Time Generator, and NPC Solo.

If you know a bit of scripting, you could also set up a piggy back menu within .[npcExist], or write a separate dialog menu for a HUD.

I’ll go into details about doing those things in a future post, but for now, let’s go super-simple and tell your bot which action sequence to perform via the chat window. To do this, you need to know the sensor channel number and the name of the action sequence.

Let’s assume that WatchTV is one of my action sequences and I want my NPC to perform it. My imaginary sensor channel is -210831, so I would type this into chat.

/-210831 WatchTV

The slash at the beginning tells the system that the following number is a chat channel – which your NPC is listening to – and WatchTV is one of the commands it is listening for (remember the listen() event?)

If I’ve done everything correctly, my NPC will start performing the WatchTV animation sequence.

Summary

That’s pretty much all there is to know. I hope you enjoyed the ride. It was fun trying to put myself in the shoes of a noob again in order to imagine everything that can possibly go wrong. I hope I’ve covered it adequately.

I’ll make a YouTube version of this shortly and hopefully that will double up as a bit of a forum. You can also post any questions down below.

I will share the NPC Solo script when time avails, so you don’t have to type commands into chat. It’s lightweight and simple to use. If you’ve managed to set up the NPC Engine, the Solo will be an easy stroll in the park. 🙂

Have a great day,

Xay Tomsen/AndrewT 2020