Basics: Aimodels

A quick introduction to AIModels

Table of Contents

Introduction to AIModels

Think of an AIModels as a little "brain" you can attach to any user and any object in your game - but more to the point, an AI can be considered as a "class" like you are used to in object-oriented programming (OOP). There are four kinds of elements in an AIModel:
  • Variables
  • Functions
  • States
  • Handlers

User AIs and Object AIs

In ShiVa, we differentiate between two types of AIModels: Object AIs and User AIs. Both AIModels are of the same general structure and are edited with the same editor module, but serve different functions, need to be coded differently and are attached to different things.

Object AIs are attached directly to an object in the scene. They define the object behaviour, how it reacts and behaves inside your game. Object AIs are limited to the scene the (parent) object "lives" in and accepts only Universal, Custom and Object Event Handlers, but no User Handlers. When the game is played, several instances of a same Object AI can be created and attached to different objects. So two objects with the same AIModel can have different behaviors at a specific time, because they are running two different instances of the same AIModel.

User AIs on the other hand are attached in Game Editor "Properties" panel. They catch the user input, manage the game (storage, server interactions, interface, load the scenes, ...) and identify the user in multiplayer games. User AIs are not limited to scenes, but are active as long as the user is active, and accept Universal, Custom and User Handlers, but no Object Handlers.

Accessing AIModel elements from script

this Keyword

"this" represents the current AI instance. To get/set any instance member, use the 'this' keyword. In User AIs, you can get the reference to the current user via:

--return the user handle to which instance is attached to

this.getUser ( )
In object AIs, you can get the reference to the object the AI is attached to using:

--return the object handle to which instance is attached to

this.getObject ( )
Important: Calling this.getObject ( ) in an AI attached to a user returns nil, and calling this.getUser ( ) in an AI attached to an object returns nil too. Keep your User and Object AIs separate!


To get the value of a variable, use this.theVariableName ( ). To set the variable value, use this.theVariableName ( value ).


To call a function with 2 parameters, use this.theFunctionName ( p1, p2 ). A function is executed immediately (synchronously) when called.


To change the current state of the AIModel, use this.theStateName ( ) or this.sendStateChange ( "theStateName" ). To change states with a delay, use this.postStateChange ( nDelay, "theStateName" ) with the delay in seconds. An AI can be in only one state at a given time.


Universal, User and Object Handlers cannot be called from script. They are triggered by the 3D engine when an event happens. Custom Handlers can be triggered by using user.sendEvent/user.postEvent and object.sendEvent/object.postEvent.