What's in a Game[]
When a game is running, it contains three primary pieces of state:
- The Scene Objects
- The loaded Lua Script Files
- The Lua Global Variables
Scene objects are the physical objects that move around your virtual world. In the standard game, there are four scene objects: the two cubes, the sky, and the ground. Normally, scene objects will bump into each other and rebound using the physics system, although some can be immune, such as the sky in the standard game.
Wild Pockets games are scripted in Lua. The programmer creates Lua script files on the Wild Pockets file server. The game contains references to these script files.
Lua, like most programming languages, has global variables. Lua globals are generally used by the script to store whatever it wishes to store. You can write a game using multiple source files, in this case, each source file is loaded in its own scope. Each scope contains global variables.
The Scene Object state can be pre-initialized from a "scene file." Scene files can also be loaded mid-game, for example to load a level.
What's in a Scene Object[]
SceneObjects are the renderable objects that move around your virtual world. A scene object has the following attributes:
- Position, Rotation, and Scale
- The 3D Model
- Meshes
- Textures and colors
- Collision volumes
- Skeleton
- Currently-playing Animations
- Physics State
- Anchored-flag
- Velocity and rotational velocity
- Lua Data
- The Lua Classname
- The Lua Data Table
- Persistent property storage
- Optional Particle System
- Other less-important attributes.
The Scene Object’s Position, Rotation, and Scale[]
Every scene object has a position, rotation, and scale. Together, these are called the object's "transform."
All coordinates in Wild Pockets are measured relative to the "world origin," an invisible stationary marker in the center of the pocket. Or to put it differently, we use absolute world coordinates wherever possible.
In general, we like to think of the X-axis as pointing "east," the Y-axis as pointing "north," and the Z-axis as pointing "up." The engine has these assumptions wired into all default values. For instance, the default gravity pulls in the negative-Z direction (ie, down). As another example, the camera naturally orients itself upright – ie, with the top of the screen in the positive-Z direction – unless you force it to do otherwise.
The Scene Object’s 3D Model[]
When a scene object is created, it is associated with a 3D model. The model is created in Max or Maya and exported into a file on the Wild Pockets file server. The command to create the object requires that you specify the file server filename of the 3D model.
The 3D model consists of some number of individual meshes. Each mesh consists of a set of polygons, all of which share the same texture. There exist commands to override the texture of a mesh, thereby changing its appearance. You can also hide or unhide an individual mesh. When you alter the texture or visibility of a mesh, you do so on a per-scene-object basis. That is, if two scene objects use the same 3D model, and you alter the texture of one, you haven’t altered the texture of the other.
Wild Pockets uses a skeletal animation system. The virtual skeleton is an interconnected system of virtual bones. It looks and functions a lot like a real-world skeleton. Each bone is a rigid object. The polygons are "rigged" to the bones, meaning they move when the underlying bone moves. A polygon which is near a joint, such as an elbow, may be rigged to multiple bones, in which case the polygon may move when either bone moves. Commands exist in the lua script to move the entire model, and also to move individual bones.
The Scene Object’s Currently-playing Animations[]
In Wild Pockets, the word "Animation" is used to mean prerecorded movements. Animations are created in Max or Maya and exported to a file on the file server. Be clear on this terminology. There are three ways to generate movement: using the physics engine, using the lua script, and by recording movements in Max or Maya. Of these three, only the recorded ones are called "animations." The other two are just called "movement." Every scene object has a list of animations that it is currently playing.
The Scene Object’s Physics State[]
By default, when you put a scene object into the world, the physics system will immediately begin operating on it. The object will fall to the ground, roll around and eventually come to a stop. If it bumps into something along the way, it will ricochet and impart inertia to the object it collided with.
There are two important physics flags: the 'anchored' flag and the 'collidable' flag. An anchored object will not be moved by the physics system. A non-collidable object will pass ghost-like through other objects.
The Scene Object's Particle System[]
A scene object may have a particle system attached to it. Particle systems are created by writing little programs in a language called 'ParticleScript.'
The Scene Object's Lua Data[]
If desired, you can write a script containing a lua class definition, and then you can cause a SceneObject to become an instance of that class by setting the SceneObject's classname. Once you do this, the SceneObject gains a data table where the Lua code can store instance variables.
In addition, the SceneObject has a persistent property storage area where you may write any data you wish. This persistent property storage is part of the SceneObject, hence it can be loaded from scene files.
Much, much more...[]
This is far from being a complete list of every piece of data in a Wild Pockets game. For instance, there are lights, there's a camera, and there's a clock, none of which were mentioned. If we were to try to give you a truly comprehensive list at this stage, it would be overwhelming. Suffice to say that the data structures listed above are the big ones - the key elements of a Wild Pockets game.
The Wild Pockets API reference, which is part of the development environment, is indeed comprehensive and includes every piece of data that can be accessed. To access this list, open the builder and select the help question mark on the right side of the screen.