Zippy uses Lua for its scripting language, and there's a lot of information on the Lua website that you may need to know before you even start to think about making objects do interesting things. If you object is simple, there's a good chance you can get through enough of this guide without learning about Lua -- but if you really want to understand what's going on, and if you have even the slightest glimmer of ambition to make a full-blown module, you're going to need it. So grab a copy of Lua from the site (make sure you get version 4.0 or 4.0.1) and start hacking away at it with the documentation. Read the rest of this topic first, though, so you know what you're getting into.

Zippy uses Lua for its scripting language, and there's a lot of information on the Lua website that you may need to know before you even start to think about making objects do interesting things. If your object is simple, there's a good chance you can get through enough of this guide without learning about Lua -- but if you really want to understand what's going on, and if you have even the slightest glimmer of ambition to make a full-blown module, you're going to need it. So grab a copy of Lua from the site (make sure you get version 4.0 or 4.0.1) and start hacking away at it with the documentation. Read the rest of this topic first, though, so you know what you're getting into.

Egoboo is supposed to be a cross platform game these days, so you always have to keep in mind the issues others will run into trying to use your scripts. One of these issues is case sensitivity. So if you're running a windows machine, you'll have to restrain you urge to be CreAtIvE aNd StRew CapItoLS alL oVeR ThE PlaCE AnD ThrOw CoNSISteNcY OuT tHe WinDow(S). Use lowercase, and use it everywhere. Likewise, us priveleged *NIX users can't do nifty things like have two files named "FiLeOne.LuA" and "fIlEoNE.lUa". Lowercase is the thing. You could use all caps if you wanted, but that's just plain annoying.

Egoboo is supposed to be a cross platform game these days, so you always have to keep in mind the issues others will run into trying to use your scripts. One of these issues is case sensitivity. So if you're running a windows machine, you'll have to restrain the urge to be CreAtIvE aNd StRew CapItoLS alL oVeR ThE PlaCE AnD ThrOw CoNSISteNcY OuT tHe WinDow(S). Use lowercase, and use it everywhere. Likewise, us priveleged *NIX users can't do nifty things like have two files named "FiLeOne.LuA" and "fIlEoNE.lUa". Lowercase is the thing. You could use all caps if you wanted, but that's just plain annoying.

%META:TOPICINFO{author="ElminI" date="1081735356" format="1.0" version="1.1"}% %META:TOPICPARENT{name="ZippyScriptingGuide"}%

Introduction to Scripting in Zippy

Zippy uses Lua for its scripting language, and there's a lot of information on the Lua website that you may need to know before you even start to think about making objects do interesting things. If you object is simple, there's a good chance you can get through enough of this guide without learning about Lua -- but if you really want to understand what's going on, and if you have even the slightest glimmer of ambition to make a full-blown module, you're going to need it. So grab a copy of Lua from the site (make sure you get version 4.0 or 4.0.1) and start hacking away at it with the documentation. Read the rest of this topic first, though, so you know what you're getting into.

Now knowing Lua will help you, certainly, but Zippy adds a number of devices, concepts, and constructions to the basic language that you will need to know about. Further, Zippy has a pretty specific methodology in place for defining new objects, and you're in trouble if you don't know what that is, too. That's what this guide is all about.

The Character System

The most fundamental concept in Zippy (as in 2.22) is the concept of Characters. Characters are defined rather broadly; they're things that have models, whose behavior can be controlled by scripts. So grub bugs and adventurers are Characters, but so are swords, anvils, rubber ducks, and pieces of furniture. If it has a model, it's a Character. Since the bulk of the scripting task is defining character types, let's take a look at the system and how it works.

Creating a Character: The Character Type

Most of the time, when you create a model, and define behavior for it, you're going to use that model and behavior many times throughout a module. So instead of defining the same behavior for each instance of a character, Zippy forces you to think long-term and define a Character Type that each character can belong to. So if you have ten thousand swords in your module, you create a single character type which is sort of a sword "pattern" or template, and then you instantiate (fill in the pattern) the type ten thousand times.

This system was part of 2.22 as well, but Zippy takes it a step further. Scimitars all have in common the fact that they are scimitars. But they also have in common with swords a number of features:

• Both are weapons
• Both are swung in a similar way
• Both do damage when they hit the enemy
• They depend on similar skills and attributes

Zippy allows you to codify these similarities using a programming principle called inheritance. We'll talk more about that in the ZippyInheritanceGuide.

Alerts and Alert Handlers

One of the biggest tasks of any character type is to handle information from the engine and translate it into action. The information comes in the form of alerts; a common example is the "bumped" alert. When a character gets the "bumped" alert, it means, "Someone bumped you, and it was that guy." Alert handlers are defined in the character type (more on that later), and they specify what a character should do when it gets that kind of alert. For example, a grub bug would spin around and bite that guy. A cactus might cause him some damage. A spikey grub bug might do both. Take a look at the technical definition and list of ZippyAlerts.

Profiles

Another task for any character type is to define what kind of physical object it represents. This is where the script references a model and a set of skins for characters to use. It's also where things like weight, attack particles, and transparency are specified. Take a look at ZippyProfiles.

Updates vs. Frames

Every once and a while, the engine goes through the list of active characters and updates the status of each one, calling all applicable alert handlers (and doing a bunch of other stuff as well). Whenever the engine does this, it is called an update.

Whenever the engine gets a chance, it goes through the list of visible things and draws each one on the screen. Whenever the engine does this, it is called a frame. Updates and frames are different things, and it will help you to know the difference!

The Particle System

Some things are better represented by 2D sprites than 3D models, and most of the time these things don't need fine-grained control from scripts. To answer this specialized need, Zippy has (as in 2.22) a system for particles. Particles, like Characters, are created to follow the patterns specified in particle types. A particle starts out with a position, a velocity, and a set of physical characteristics, and scripts are not expected to take much control from that point onwards. ZippyParticles has more detail.

Particle Alerts

Among the ZippyAlerts you will see a number of alerts whose names start with "particle." When a particle is created, it may have an owner -- a character who receives notification for all of the things that happen to the particle during its life. This notification comes in the form of alerts, which are delivered to the character type for a character in the form of a call to its alert handler. So if a torch makes a particle for a little bit of its flame, and that flame bumps into something, it will receive a "particle_bumped" alert, which means, "One of your particles bumped into that guy."

Examples

Enough theory. Here are some examples.

The Rock

Let's make an object that sits in one place and doesn't do anything else:

register_type{
  name = "Rock",
  profile = {
    invincible = 1,
    weight = 212,
    bump_size = 45,     -- this is how wide the model is, in 256ths of a map tile
    bump_dampen = 0.25, -- this means the rock is fairly difficult to move (lower is more difficult)
    model = "rock.md2", -- the name of the model file
    skins = {
      normal = Skin{
        name = "Just a rock",
        texture = "rock.bmp",
        icon = "rock_icon.bmp"
      }
    }
  }
}

Let's go through this set by step:

register_type{
  name = "Rock",

This part tells Zippy that the character type will be called "Rock". Technically, the register_type function creates a Lua value and stores it in a global variable under this name -- the important point to remember for now is that the name here has to be a valid variable name (only letters, numbers, and underscores).

  profile = {
    invincible = 1,
    weight = 212,
    bump_size = 45,     -- this is how wide the model is, in 256ths of a map tile
    bump_dampen = 0.25, -- this means the rock is fairly difficult to move (lower is more difficult)
    model = "rock.md2"  -- the name of the model file

This is part of the profile we mentioned earlier; this rock is invincible and pretty heavy, and things that bump into it will bounce off, not moving the rock very much. The model is also given here.

    skins = {
      normal = Skin{
        name = "Just a rock",
        texture = "rock.bmp",
        icon = "rock_icon.bmp"
      }
    }

This is another part of the profile, specifying the skin set. Here we have one skin, the "normal" one. You must specify a texture bitmap and an icon.

Getting it Into a Module

Make a subdirectory "rock.obj" under the "objects" directory in your Zippy distribution. Put the script above into a file called "script.lua" in that directory, and put the data files (model, skin, and icon) in the same directory. Edit "modules/[module name].mod/objects/loadai.lua", adding this line:

dofile("objects/rock.obj/script.lua")

Now edit "modules/[module name].mod/gamedat/spawn.lua" and add this line:

Rock(12.2, 23.0, 1.1, "A Rock", NeutralTeam, "normal", -1, nil)

See ZippyCharacterType for the exact meanings of these parameters; you'll probably want to change the position, and the team must be one that's defined in the file you're editing.

Congradulations -- you've made an object!

Scripting Conventions

Before we bring this whirlwind tour to an end, a final note about conventions -- these are the oil that keep Egoboo running smoothly, preventing it from balling up into a tangled mess like so much overcooked spaghetti.

Where to Put your Files

If you look in the root of your Egoboo installation, you will see the following directories:

basicdat/                    
cartman/                    
code/                    
mazeman/                    
modules/                    
objects/

The important ones for you are "basicdat," "objects," and "modules." "basicdat" stores scripts of a global nature, which have no specific link to any character or character type. For example, the name generator is stored there, along with ArakoN's memetic framework. "objects" is where character types go, along with their data files. There are two basic types of character types in this directory; ones that are meant to be inserted as-is into a module, and ones that define general sorts of characteristics for other character types to use. For objects in the former category, their scripts are all stored directly inside of the "objects" directory. For example, the Flammable type was never intended to be instantiated (spawned) anywhere, so it goes in "objects/flammable.lua". Each character type that is productive (i.e. intended to produce actual characters) goes in its own directory with all of its data files. So the Rogue has a directory, "objects/rogue.obj" -- inside this directory is the actual script, "objects/rogue.obj/script.lua", and all of the data files (e.g. the model in "objects/rogue.obj/rogue.md2").

The last directory you'll want to worry about is "modules". It has, though you might not believe it from the name, all of the modules that Egoboo can use. Each module has its own directory; for example, the adventurer start module is in "modules/advent.mod". Each module directory has two subdirectories, "gamedat" and "objects" -- these are a holdover from 2.22, and they will likely disappear in later releases, so keep your eyes peeled for changes. Each directory has one file, a script: "gamedat" has "spawn.lua" and "objects" has "loadai.lua". "spawn.lua" is where all the characters are initially spawned, and "loadai.lua" does two things: firstly, it includes (see ZippyNamespaces or hold out for a later guide) all of the character scripts that are going to be used in the module, and secondly, it defines all of the teams (see ZippyTeams).

A Note About Case (Accusative, Vocative, ... -- oh, wait)

Egoboo is supposed to be a cross platform game these days, so you always have to keep in mind the issues others will run into trying to use your scripts. One of these issues is case sensitivity. So if you're running a windows machine, you'll have to restrain you urge to be CreAtIvE aNd StRew CapItoLS alL oVeR ThE PlaCE AnD ThrOw CoNSISteNcY OuT tHe WinDow(S). Use lowercase, and use it everywhere. Likewise, us priveleged *NIX users can't do nifty things like have two files named "FiLeOne.LuA" and "fIlEoNE.lUa". Lowercase is the thing. You could use all caps if you wanted, but that's just plain annoying.

Conclusion

So that's it for the intro. Have fun with it.

-- ElminI - 12 Apr 2004