Scripting: Difference between revisions

From EDukeWiki
Jump to navigation Jump to search
 
(94 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{EDuke32 Intro}}
{{EDuke32 Intro}}
<div class="floatleft">__NOTOC__</div> <!-- changed to NOTOC to get rid of it temporarily -->
<div class="floatright">__TOC__</div>
==About This Guide==
==About This Guide==
===Intro===
===Intro===
Line 6: Line 6:


===CON Basics===
===CON Basics===
*[[:Category:Duke3D_1.3/1.5_commands|default commands]]
*full command list
**[[Full command list|alphabetized]]
**[[:Category:All commands|categorized]]
If you are not already familiar with the default commands, the authors of this guide recommend the following guide, imported into the EDukeWiki for your convenience:
If you are not already familiar with the default commands, the authors of this guide recommend the following guide, imported into the EDukeWiki for your convenience:
* [[Confaq42|Con FAQ 4.2 by Jonah Bishop (note: some sections have been shuffled around a bit by TX)]]  
* [[Confaq42|Con FAQ 4.2 by Jonah Bishop (note: some sections have been shuffled around a bit by TX)]]  


Another good source of basic information is the following FAQ:
Other good sources of basic information are the following FAQs:
* [http://rtcm.thecomitatus.com/knowledge-base/downloads-rtcm/duke3d-faqs-con/H_CONFAQ.zip Con Editing Information v1.3 by James Ferry]
* [http://dukertcm.com/knowledge-base/downloads-rtcm/duke3d-faqs-con/H_CONFAQ.zip Con Editing Information v1.3 by James Ferry]
* [http://dukertcm.com/knowledge-base/downloads-rtcm/duke3d-faqs-con/conedit.zip Con Editing FAQ v2.0 by Joris B. Weimar]


==Gamevars==
==CON Mechanics==


===Overview===
===Gamevars===
*[[gamevar|gamevars]]
Gamevars were introduced in [[WWII GI]] and remain the single most important aspect of the new commandset.  Everything that sets EDuke32 scripting apart from regular Duke Nukem 3D scripting revolves around gamevars.  Gamevars work similarly to integer variables in various programming languages, allowing the user to store, manipulate, and compare various information.  Prior to gamevars, the only usable alternatives were manipulations of inventory item counters and move commands.


===Types===
====Overview====
There are three basic types of gamevar, each type storing a signed 32-bit fixed-point integer.  The three basic types are as follows:
 
[[Gamevar]]s are the heart and soul of modern EDuke32 CON scripting.  Gamevars are signed 32-bit fixed-point integer variables, a ubiquitous staple of programming languages. Gamevars are used to store, manipulate, and compare various numerical informationPrior to gamevars' introduction in [[WWII GI]], the only usable alternatives were manipulations of inventory item counters and move commands.
 
====Scope====
There are three scopes of gamevars.
* '''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.
* '''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:
For example:


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


This line tells the game to create a variable named "shots_fired" which is initialized to 0.  But wait -- what's the second 0 for?  If you're asking yourself this question, go back and read the actual page on [[gamevar|gamevars]].  Now that you know that gamevars have flags which must be declared along with the var's name and value, let's continue.
This line tells the game to create a variable named "shots_fired" which is initialized to 0.  But wait -- what's the second 0 for?  If you're asking yourself this question, go back and read the actual page on [[gamevar]]s.  Now that you know that gamevars have flags which must be declared along with the var's name and value, let's continue.


So, we've created a gamevar.  Now what?  For this example, we'll 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:
So, we've created a gamevar.  Now what?  For this example, we'll 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:
Line 38: Line 43:
* '''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-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:
* '''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 [[tic]].  For example, suppose you want each monster to keep track of how many bullets it has fired:


   gamevar shots_fired 0 2
   gamevar shots_fired 0 2
Line 47: Line 52:
'''There are also some [[pre-defined gamevars]] and special [[constantly updated gamevars]] which should only be used in certain ways.'''
'''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====


Custom variables, or "gamevars" are declared with the [[gamevar]] command.
Custom variables, or "gamevars" are declared with the [[gamevar]] command.


The syntax for defining a gamevar is:
The syntax for defining a gamevar is:
::gamevar <varname> <value> <flags>
: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.  
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.  
Line 60: Line 65:
The <flags> may be set to either 0 (global), 1 (per-player), or 2 (per-actor).
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:
*[[ifvar conditions]]
*[[gamevar operators]]


*[[setvar]], [[setvarvar]]
===Members of game structures===
*[[addvar]], [[addvarvar]]
*[[subvar]], [[subvarvar]]
*[[mulvar]], [[mulvarvar]]
*[[divvar]], [[divvarvar]]
*[[randvar]], [[randvarvar]]


And some of the more rarely used ones:
*[[structure access]]
*[[full list of structure members]]
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.


*[[andvar]], [[andvarvar]]
The most common of these structures is that of the veritable '''actor'''. Objects in the game world, such as monsters, missiles, bits of debris, and so on, are referred to as "sprites" (because they are typically rendered as 2D pictures).  Sprites that execute code are usually referred to as "actors". Every sprite has its own data structure containing all of the member elements in the list linked to above.  Various original CON commands, such as "cstat", "spritepal", "sizeat", etc. work by changing values in the sprite structure of the actor executing the command.  These structure members can be modified directly in an EDuke32 script by using the [[setactor]] command.  Commands like setactor enable us to modify every member of the structure, even those that could not be accessed with the original scripting system. See [[getactor]] and [[setactor]] to see how these commands are used.
*[[sin]], [[cos]]
*[[orvar]], [[orvarvar]]
*[[shiftvarl]], [[shiftvarr]]
*[[xorvar]], [[xorvarvar]]


To test the values of gamevars, the following commands are used:
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.  [[Make Nightvision light rooms|This example]] shows how to get a member of the player structure into a variable, check its value, then alter a member of the player structure accordingly.


*[[ifvarand]]
The '''tsprite''' structure is an interesting one. It operates on sprites within the context of just the renderer. This means that you can alter the properties of what is displayed without altering the sprite itself. The possibilities are endless with this functionality. It is also useful for intercepting and redirecting hardcoded behavior.
*[[ifvarvarand]]
*[[ifvare]]
*[[ifvarg]]
*[[ifvarl]]
*[[ifvarn]]
*[[ifvarvare]]
*[[ifvarvarg]]
*[[ifvarvarl]]
*[[ifvarvarn]]


A complete list of primitives is available [[Full_command_list|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.  All commands which accept read-only gamevars will also accept constants in place of them.
The '''input''' structure holds data about what game-defined control functions are being operated.


==Members of game structures==
Check out the pages linked above for a full index of the various structures available in scripting.


===Overview===
===Events===
*[[full list of structure members]]
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 [[full list of structure members|here]].


===Player===
*[[EDuke32 event list|events list]]
*[[members of the player structure]]
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.  [[Make_Nightvision_light_rooms|This example]] shows how to get a member of the player structure into a variable, check its value, then alter a member of the player structure accordingly.


===Actor / Sprite===
EDuke32 provides both an object-oriented and a procedural interface to the game's internal workingsAs 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 sectionAs 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.
*[[Members of the sprite and hittype structures]]
Objects in the game world, such as monsters, missiles, bits of debris, and so on, are referred to as "sprites" (because they are typically rendered as 2D pictures)Sprites that execute code are usually referred to as "actors". Every sprite has its own data structure containing all of the member elements in the list linked to above.  Various original CON commands, such as "cstat", "spritepal", "sizeat", etc. work by changing values in the sprite structure of the actor executing the commandThese structure members can be modified directly in an EDuke32 script by using the [[setactor]] command.  Commands like setactor enable us to modify every member of the structure, even those that could not be accessed with the original scripting system. See [[getactor]] and [[setactor]] to see how these commands are used.


===Sector===
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.
*[[Members of the sector structure]]
You can control the sectors with the [[getsector]] and [[setsector]] commands.


===Wall===
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 [[EDuke32 event list|events]].  Furthering the similarity, onevent must be terminated by the equivalent of an [[enda]] or an [[ends]], an [[endevent]].
*[[Members of the wall structure]]
You can control the walls in the game with the [[getwall]] and [[setwall]] commands


===Game configuration===
The following example of event code will cause the player to have a full first aid kit every time the inventory is reset (e.g. when the player starts a game):
*[[Members of the userdef structure]]
The userdef structures are controlled with the [[getuserdef]] and [[setuserdef]] commands.


===Player input===
onevent EVENT_RESETINVENTORY
*[[Members of the input structure]]
    setplayer[THISACTOR].firstaid_amount 100
The input structures are controlled with the [[getinput]] and [[setinput]] commands.
endevent


==Events==
===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).


===Overview===
*[[rotatesprite]]
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 [[events|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.
*[[screentext]]


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.
===Custom projectiles===
EDuke32 adds the ability to create new projectiles in addition to the default types. A few basic types exist (shorthand: melee, hitscan (bullets), and visible projectiles like RPGs) which can be used to create a nearly infinite variety of weapon types and even some entirely new effects, such as new types of debris, gibs, clouds of billowing smoke, et cetera.


===Event use===
Projectiles are defined via the [[defineprojectile]] command. The syntax for this command is:
*[[events]]
  defineprojectile <tilenum> <function> <value>
Using an event is very easy &mdash; 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 [[EDuke32 event list|events]]. Furthering the similarity, onevent must be terminated by the equivalent of an [[enda]] or an [[ends]], an [[endevent]].


The following example of event code will cause the player to have a full first aid kit every time the inventory is reset (e.g. when the player starts a game):
These values can be modified with the [[getprojectile]], [[getthisprojectile]] and [[setprojectile]], [[setthisprojectile]] commands.


    onevent EVENT_RESETINVENTORY
===String manipulation===
    setplayer[THISACTOR].firstaid_amount 100
    endevent


[[:Category:String manipulation|Strings]] (lines of text) are called "quotes" in Duke Nukem 3D. String manipulation consists of some simple copying and concatenation commands, as well as the ability to print the text to the screen and to the log file.


====A note on synchronization====
==Scripting Guidelines==
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==
When scripting, there are guidelines that you should follow in order to keep your code clean, concise, correct, and optimized.
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===
===Design===
*[[rotatesprite]]
*[[gametext]]
*[[minitext]]
*[[digitalnumber]]
*[[myos]] (deprecated)
*[[myospal]] (deprecated)
*[[myosx]] (deprecated)
*[[myospalx]] (deprecated)


===Changing the rendering properties of a sprite in the world===
*If you are making a mini-mod, consider creating a [[CON mutator]].
[[Members of the tsprite structure]]


==Custom projectiles==
===Formatting===
===Overview===
*Always comment your code! It will help you and others later, and it will also help keep the code straightforward.
EDuke32 adds the ability to create new projectiles in addition to the default types. A few basic types exist (shorthand: melee, bullet, and slow projectile) which can be used to create a nearly infinite variety of weapon types and even some entirely new effects, such as new types of debris, gibs, clouds of billowing smoke, et cetera.
*Indentation is key. Every level of code ("if" and "[[switch]]" statements, loops, and [[:Category:All commands#Block Delimiting|delimited blocks]]) should be indented with four spaces. TAB characters should be avoided.
*[[Label]]s, [[gamevar]]s, [[action]]s, [[move]]s, and [[AI]]s are case-sensitive and cannot start with numbers. Do not use the same names as CON commands.
*<code>if<something> [[nullop]] [[else]] (...)</code> is a common construction used when an if condition lacks a NOT variant.
*Only use '''{''' braces '''}''' for if conditions when you intend to execute more than one command if the condition is true. If you only have one command, do not use braces. Braces tell the CON compiler specifically to branch, which slows down your code a tiny fraction. Another if condition counts as one command.
**The exception is that if you have an [[else]] following multiple non-braced if conditions where it may be ambiguous, you need to add braces to ensure the else is used correctly.
*Because [[event]]s can be defined multiple times in an additive fashion, keep separate instances in your own organization scheme based on the '''function''' of your events. Writing a con file named '''events.con''' is HIGHLY discouraged.


===Defining custom projectiles===
===Methodology===
Projectiles are defined via the [[defineprojectile]] command. The syntax for this command is:
*Not all "temp" variables are created equal. [[Gamevar]]s used only to perform a mathematical calculations and not to store values afterwards should be declared GLOBAL to save memory. Remember, the game VM that runs CON code will always be single-threaded by nature. If you are using a [[gamevar]] to store a value to be preserved between [[tic]]s, simply to save it for use later, or for a construct like a counter, it should be declared PERACTOR.
defineprojectile <tilenum> <function> <value>


Before using this command list of defines should be created:
==Links==
define PROJ_WORKSLIKE 1
*full command list
define PROJ_SPAWNS 2
**[[Full command list|alphabetized]]
define PROJ_SXREPEAT 3
**[[:Category:All commands|categorized]]
define PROJ_SYREPEAT 4
*[[gamevar]]s
define PROJ_SOUND 5
define PROJ_ISOUND 6
define PROJ_VEL 7
define PROJ_EXTRA 8
define PROJ_DECAL 9
define PROJ_TRAIL 10
define PROJ_TXREPEAT 11
define PROJ_TYREPEAT 12
define PROJ_TOFFSET 13
define PROJ_TNUM 14
define PROJ_DROP 15
define PROJ_CSTAT 16
define PROJ_CLIPDIST 17
define PROJ_SHADE 18
define PROJ_XREPEAT 19
define PROJ_YREPEAT 20
define PROJ_PAL 21
define PROJ_EXTRA_RAND 22
define PROJ_HITRADIUS 23
define PROJ_VEL_MULT 24
define PROJ_OFFSET 25
define PROJ_BOUNCES 26
define PROJ_BSOUND 27
define PROJ_RANGE 28
 
These defines are used to fill the <function> block of defineprojectile.
 
===Manipulating custom projectiles mid-game===
[[Members of the tsprite structure]]
==String manipulation==
===Quote redefinition mid-game===
redefinequote <quotenumber> <string> // sets the quote number <quotenumber>'s text to <string>
===Copying and concatenation===
qstrcpy <quotenumber1> <quotenumber2> // sets the text of <quotenumber1> to the text of <quotenumber2>
qstrcat <quotenumber1> <quotenumber2> // adds the text of <quotenumber2> to the text of <quotenumber1>
 
==Quick link list==
*[[:Category:Duke3D_1.3/1.5_commands|default commands]]
*[[gamevar|gamevars]]
*[[pre-defined gamevars]]
*[[pre-defined gamevars]]
*[[constantly updated gamevars]]
*[[constantly updated gamevars]]
*[[Members of the input structure]]
*[[full list of structure members|structure members]]
*[[Members of the userdef structure]]
*[[EDuke32 event list|event list]]
*[[Members of the wall structure]]
*[[:Category:Screen drawing commands|screen drawing commands]]
*[[Members of the sector structure]]
*[[defineprojectile|projectile information]]
*[[Members of the sprite and hittype structures]]
*[[Tutorials]]
*[[members of the player structure]]
*[[full list of structure members]]
*[[events]]
 
==References==
*[[Full command list]]
*[[EDuke32 event list]]
*[[Full list of structure members]]


*[[:Category:All commands|Categorized documentation]]
[[Category:Scripting documentation]]

Latest revision as of 12:58, 31 January 2014

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 assumes both that the reader comprehends and understands the basic CON system as was seen in Duke Nukem 3D 1.3D/1.5, and that the reader is familiar with a few basic programming concepts.

CON Basics

If you are not already familiar with the default commands, the authors of this guide recommend the following guide, imported into the EDukeWiki for your convenience:

Other good sources of basic information are the following FAQs:

CON Mechanics

Gamevars

Overview

Gamevars are the heart and soul of modern EDuke32 CON scripting. Gamevars are signed 32-bit fixed-point integer variables, a ubiquitous staple of programming languages. Gamevars are used to store, manipulate, and compare various numerical information. Prior to gamevars' introduction in WWII GI, the only usable alternatives were manipulations of inventory item counters and move commands.

Scope

There are three scopes of gamevars.

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

  gamevar shots_fired 0 0 // gamevar declarations occur outside of states, events, and actor code

This line tells the game to create a variable named "shots_fired" which is initialized to 0. But wait -- what's the second 0 for? If you're asking yourself this question, go back and read the actual page on gamevars. Now that you know that gamevars have flags which must be declared along with the var's name and value, let's continue.

So, we've created a gamevar. Now what? For this example, we'll 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 counter

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 tic. 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, or "gamevars" are declared with the gamevar command.

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 must be a whole number.

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

Members of game structures

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.

The most common of these structures is that of the veritable actor. Objects in the game world, such as monsters, missiles, bits of debris, and so on, are referred to as "sprites" (because they are typically rendered as 2D pictures). Sprites that execute code are usually referred to as "actors". Every sprite has its own data structure containing all of the member elements in the list linked to above. Various original CON commands, such as "cstat", "spritepal", "sizeat", etc. work by changing values in the sprite structure of the actor executing the command. These structure members can be modified directly in an EDuke32 script by using the setactor command. Commands like setactor enable us to modify every member of the structure, even those that could not be accessed with the original scripting system. See getactor and setactor to see how these commands are used.

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. This example shows how to get a member of the player structure into a variable, check its value, then alter a member of the player structure accordingly.

The tsprite structure is an interesting one. It operates on sprites within the context of just the renderer. This means that you can alter the properties of what is displayed without altering the sprite itself. The possibilities are endless with this functionality. It is also useful for intercepting and redirecting hardcoded behavior.

The input structure holds data about what game-defined control functions are being operated.

Check out the pages linked above for a full index of the various structures available in scripting.

Events

EDuke32 provides both an object-oriented and a procedural 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.

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.

The following example of event code will cause the player to have a full first aid kit every time the inventory is reset (e.g. when the player starts a game):

onevent EVENT_RESETINVENTORY
    setplayer[THISACTOR].firstaid_amount 100
endevent

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).

Custom projectiles

EDuke32 adds the ability to create new projectiles in addition to the default types. A few basic types exist (shorthand: melee, hitscan (bullets), and visible projectiles like RPGs) which can be used to create a nearly infinite variety of weapon types and even some entirely new effects, such as new types of debris, gibs, clouds of billowing smoke, et cetera.

Projectiles are defined via the defineprojectile command. The syntax for this command is:

defineprojectile <tilenum> <function> <value>

These values can be modified with the getprojectile, getthisprojectile and setprojectile, setthisprojectile commands.

String manipulation

Strings (lines of text) are called "quotes" in Duke Nukem 3D. String manipulation consists of some simple copying and concatenation commands, as well as the ability to print the text to the screen and to the log file.

Scripting Guidelines

When scripting, there are guidelines that you should follow in order to keep your code clean, concise, correct, and optimized.

Design

  • If you are making a mini-mod, consider creating a CON mutator.

Formatting

  • Always comment your code! It will help you and others later, and it will also help keep the code straightforward.
  • Indentation is key. Every level of code ("if" and "switch" statements, loops, and delimited blocks) should be indented with four spaces. TAB characters should be avoided.
  • Labels, gamevars, actions, moves, and AIs are case-sensitive and cannot start with numbers. Do not use the same names as CON commands.
  • if<something> nullop else (...) is a common construction used when an if condition lacks a NOT variant.
  • Only use { braces } for if conditions when you intend to execute more than one command if the condition is true. If you only have one command, do not use braces. Braces tell the CON compiler specifically to branch, which slows down your code a tiny fraction. Another if condition counts as one command.
    • The exception is that if you have an else following multiple non-braced if conditions where it may be ambiguous, you need to add braces to ensure the else is used correctly.
  • Because events can be defined multiple times in an additive fashion, keep separate instances in your own organization scheme based on the function of your events. Writing a con file named events.con is HIGHLY discouraged.

Methodology

  • Not all "temp" variables are created equal. Gamevars used only to perform a mathematical calculations and not to store values afterwards should be declared GLOBAL to save memory. Remember, the game VM that runs CON code will always be single-threaded by nature. If you are using a gamevar to store a value to be preserved between tics, simply to save it for use later, or for a construct like a counter, it should be declared PERACTOR.

Links