Scripting: Difference between revisions

From EDukeWiki
Jump to navigation Jump to search
Line 20: Line 20:
===Types===
===Types===
There are three basic types of gamevar, each type storing a signed 32-bit fixed-point integer.  The three basic types are as follows:
There are three basic types of gamevar, each type storing a signed 32-bit fixed-point integer.  The three basic types are as follows:
* Global variable: A global variable will be the same for any actor it is used in. Changing a global variable changes it for all actors in the game.
* Global variable: If a variable is declared as global, there is only one copy of it which may be accessed by any actor in the game.
* Per-player variable: A per-player variable may be set independently for each player in the game.  If a player performs an action that triggers a per-player variable change within an event or the APLAYER actor code, it will only change for the player that initiated that action.  If an actor changes a per-player variable, it will change for the closest player to the actor that changed it.
* Per-actor variable: A per-actor variable may be independently assigned to each copy of an actor in the game.


There are also several [[pre-defined gamevars]] and special [[constantly updated gamevars]] which should only be used in certain ways.
For example, suppose you declare a global variable:
 
  gamevar shots_fired 0 0 // gamevar declarations must not occur inside states, events, or actor code
 
This line tells the game that there is a variable named "shots_fired" which is initialized to 0 (the first 0) and is global (the second 0).
You could then find the places in the GAME.CON code where the command "shoot SHOTSPARK1" occurs, and in each instance add the line "addvar shots_fired 1", so that in each case it looks like this:
 
  shoot SHOTSPARK1
  addvar shots_fired 1 // increments the global var
 
This will make the shots_fired var increment each time an enemy fires a SHOTSPARK1 projectile.
 
* Per-player variable: If a variable is declared as per-player, there is one copy of it for each player in the game, meaning that the variable is set independently for each player.  If a player performs an action that triggers a per-player variable change within an event or the APLAYER actor code, it will only change for the player that initiated that action.  If an actor changes a per-player variable, it will change for the closest player to the actor what changed it.  You can use the [[setplayervar]] command to set a per-player var for a particular player who is not the closest one, but this is only necessary in multiplayer games (and even then it is seldom necessary).  In single player games, there is little practical difference between a global gamevar and a per-player variable.
 
* Per-actor variable: If a variable is declared as per-actor, then there is separate copy of it for each sprite in the game.  That means that every monster, projectile, player, decorative sprite -- pretty much anything in the game that isn't a wall or sector -- has its own copy of the variable.  This is useful if you want to have actors other than the player store information for more than one tick.  For example, suppose you want each monster to keep track of how many bullets it has fired:
 
  gamevar shots_fired 0 2
 
This line tells the game that there is a variable named "shots_fired" which is initialized to 0 (the 0) and is per-actor(the 2).
With the gamevar declared, you could then add code to the monsters to increment the var when firing shots (just like in the example above for global gamevars).  Since the gamevar is per-actor, the same code would now increment the variable separately for each monster. 
 
There are also some [[pre-defined gamevars]] and special [[constantly updated gamevars]] which should only be used in certain ways.


===Use and manipulation===
===Use and manipulation===

Revision as of 16:28, 15 April 2007

EDuke32 Scripting

About This Guide

Intro

This guide will get you started with the basic aspects of EDuke32's commands -- those which set it apart from vanilla DN3D. This guide makes no assumptions regarding the programming experience of the reader, other than that the reader comprehends and understands the basic CON system as was seen in Duke Nukem 3D 1.3D/1.5.

CON Basics

As stated, this guide assume that you are familiar with the original CON code from Duke3D. If you are not already familiar with the default commands, the authors of this guide recommend the following guide to the basics, imported into the EDukeWiki for your convenience:

Another good source of basic information is the following FAQ:

Gamevars

Overview

Gamevars were introduced in WW2GI and remain the most important aspect of the new commandset. Gamevars work like variables in programming languages, allowing the user to store, manipulate, and compare data. Prior to gamevars, the only usable alternatives were manipulations of inventory item counters and move commands.

Types

There are three basic types of gamevar, each type storing a signed 32-bit fixed-point integer. The three basic types are as follows:

  • Global variable: If a variable is declared as global, there is only one copy of it which may be accessed by any actor in the game.

For example, suppose you declare a global variable:

  gamevar shots_fired 0 0 // gamevar declarations must not occur inside states, events, or actor code

This line tells the game that there is a variable named "shots_fired" which is initialized to 0 (the first 0) and is global (the second 0). You could then find the places in the GAME.CON code where the command "shoot SHOTSPARK1" occurs, and in each instance add the line "addvar shots_fired 1", so that in each case it looks like this:

  shoot SHOTSPARK1
  addvar shots_fired 1 // increments the global var

This will make the shots_fired var increment each time an enemy fires a SHOTSPARK1 projectile.

  • Per-player variable: If a variable is declared as per-player, there is one copy of it for each player in the game, meaning that the variable is set independently for each player. If a player performs an action that triggers a per-player variable change within an event or the APLAYER actor code, it will only change for the player that initiated that action. If an actor changes a per-player variable, it will change for the closest player to the actor what changed it. You can use the setplayervar command to set a per-player var for a particular player who is not the closest one, but this is only necessary in multiplayer games (and even then it is seldom necessary). In single player games, there is little practical difference between a global gamevar and a per-player variable.
  • Per-actor variable: If a variable is declared as per-actor, then there is separate copy of it for each sprite in the game. That means that every monster, projectile, player, decorative sprite -- pretty much anything in the game that isn't a wall or sector -- has its own copy of the variable. This is useful if you want to have actors other than the player store information for more than one tick. For example, suppose you want each monster to keep track of how many bullets it has fired:
  gamevar shots_fired 0 2

This line tells the game that there is a variable named "shots_fired" which is initialized to 0 (the 0) and is per-actor(the 2). With the gamevar declared, you could then add code to the monsters to increment the var when firing shots (just like in the example above for global gamevars). Since the gamevar is per-actor, the same code would now increment the variable separately for each monster.

There are also some pre-defined gamevars and special constantly updated gamevars which should only be used in certain ways.

Use and manipulation

Custom variables are defined with the gamevar command, and the term gamevar is therefore used to describe custom variables in EDuke32.

The syntax for defining a gamevar is:

gamevar <varname> <value> <flags>

You may use upper or lowercase letters for <varname>. EDuke32 is case-sensitive, so a var named "EXAMPLE1" is different from "example1." Variable names should not begin with a digit.

The <value> of the gamevar may be positive or negative and cannot include fraction.

The <flags> may be set to either 0 (global), 1 (per-player), or 2 (per-actor).

Manipulation of gamevars is accomplished by using a variety of commands that range in functionality from simple mathematical functions to grabbing internal values for manipulation in the CONs. Here are a few of the more common variable manipulation primitives:

And some of the more rarely used ones:

To test the values of gamevars, the following commands are used:

Note that a complete list of primitives is, of course, available here. The importance of manipulating gamevars will become clear when we get to talking about getting and setting the members of the various structures in the game. Also note that as of EDuke32 1.3.0, all commands which accept read-only gamevars will also now accept constants in place of them.

Members of game structures

Overview

EDuke32, like prior EDuke iterations, gives you access to game structures--basic elements of the game such as the player, sprites, walls, and sectors--and their predefined property variables, or members. There are many different structures which can be accessed, and a list of the common ones can be found here.

Player

The members of the player structure are controlled using the getplayer and setplayer commands. The player structure members deal with properties unique to the player which are not shared with other actors. These include variables associated to the players weapons, inventory items, special animations, jumping counters, etc. See the complete list of members of the player structure for details.

Actor

Members of the sprite and hittype structures

Sprite

Hittype

Spriteext

Sector

Members of the sector structure

Wall

Members of the wall structure

Game configuration

Members of the userdef structure

Player input

Members of the input structure

Events

Overview

EDuke32 provides both an object-oriented and an event-oriented interface to the game's internal workings. As you already know, the object-oriented part of Duke is the actor system -- in contrast to that, we'll be talking about the event-oriented portion in this section. As the name suggests, an event is a block of code that is triggered when a certain event in the game happens. Events in the game are triggered internally whenever a certain point in the code is reached.

Events are a key component in the manipulation of the game. Using events, we can do a variety of things such as intercept keypresses, draw to the screen (more on this later), redefine what a player does when certain actions are executed, et cetera.

Event use

Using an event is very easy — similar to the actor or state primitives, onevent is the primitive used to start the definition of a block of code to be associated with one of the events. Furthering the similarity, onevent must be terminated by the equivalent of an enda or an ends, an endevent.

A note on synchronization

Events introduce the ability for CON code to be run in a manner that isn't synchronized. For example, display events may run a different number of times on each individual system in multiplayer. If you want your mod to function properly in multiplayer, it is very important to note whether an event is synchronized or not. Typically, you'll just want to avoid doing anything that changes the game state (including ifrnd and randvar) in display code.

Drawing to the screen

The ability to properly draw to the screen is a huge improvement over the hackish abominations involving quotes and unused characters that we were forced to endure when using 1.3d and 1.5. There are several different drawing commands available, ranging in functionality from drawing graphics to the screen to printing text stored in quotes (see the section on string manipulation for more information).

Drawing commands

Custom projectiles

Defining custom projectiles

Manipulating custom projectiles mid-game

String manipulation

Quote redefinition mid-game

Copying and concatenation

Dynamic quotes

References