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:

• Con FAQ 4.2 by Jonah Bishop (note: some sections have been shuffled around a bit by TX)
  • Download stand-alone zipped version (original version from 1999 in .txt format)

Another good source of basic information is the following FAQ:

• Con Editing Information v1.3 by James Ferry

Gamevars

About

Gamevars were introduced in WW2GI and remain the most important aspect of the new commandset. Gamevars allow you to store, manipulate, and execute code based on defined values. Prior to gamevars, the only usable alternatives were manipulations of inventory item counters and were, as you can imagine, very limited.

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: 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.
• 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.

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.

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:

• addvar, addvarvar
• divvar, divvarvar
• mulvar, mulvarvar
• randvar, randvarvar
• subvar, subvarvar
• setvar, setvarvar

And some of the more rarely used ones:

• andvar, andvarvar
• sin, cos
• orvar, orvarvar
• shiftvarl, shiftvarr
• xorvar, xorvarvar

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.

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.

Synchronised and display code

Events introduce the ability for con code to be run in an unsynchronised manner. For example display events may run different numbers of times on different systems. If you wan't your mod to be usable in multiplayer it is important to be sure whether an event is a synchronised event or a display event and avoid doing anything that changes the game state (including ifrnd and randvar) in display code.

onevent and endevent

onevent is the command used to start the definition of a block of code to be associated with one of the events. Similiar to the actor keyword, onevent must be terminated by the equivalent of enda, an endevent.

eventloadactor

eventloadactor runs when an actor is loaded into the map. Despite the name it is not a game event but an entirely seperate type of block ended with enda. It is most usefull for moving settings out of hitags and lotags before they have unwanted hardcoded effects.

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

• rotatesprite
• gametext
• minitext
• digitalnumber
• myos (deprecated)
• myospal (deprecated)
• myosx (deprecated)
• myospalx (deprecated)