M32 script commands: Difference between revisions

From EDukeWiki
Jump to navigation Jump to search
added fixrepeats, minor changes
→‎quote commands: add drawlabel
(15 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Build Intro}}
{{M32Script Intro}}
{{M32Script Intro}}
----
----
Line 9: Line 10:
'''D''': differs from CON, '''X''': deprecated/do not use (yet)<br>
'''D''': differs from CON, '''X''': deprecated/do not use (yet)<br>
'''''var/array/special''''': must be writable, [''something'']: optional command field
'''''var/array/special''''': must be writable, [''something'']: optional command field
''A note on the current sprite'': when the current sprite index ''I'' is set (that is, greater or equal zero), all functions that act on sprites by pointer ('''S''') are also available since the sprite pointer is set to point to the ''sprite[]'' array at index ''I'' in this case. The converse is not true, however: the sprite pointer could be set to a sprite structure other than the main ''sprite[]'' array (such as the ''tsprite[]'' array of sprites drawn on the screen), so code in a scope where the sprite pointer has been set ('''s''') cannot use functions accessing the ''sprite[]'' array ('''I''').


====basic commands====
====basic commands====
Line 14: Line 17:
*[[Define]]
*[[Define]]
*[[Include]]
*[[Include]]
*[[Defstate]] (only for defining)
*[[Defstate]] | (only for defining)
*[[Ends]]
*[[Ends]]
*[[State]] '''D''' (only for calling)
*[[State]] | '''D''' (only for calling)
*[[Onevent]]
*[[Onevent]]
*[[Endevent]]
*[[Endevent]]
*[[Gamevar]] '''D''' (different flags)
*[[Gamevar]] | '''D''' (different flags)


====control flow====
====control flow====
*[[Else]]
*[[Else]]
*[[Return]] '''D''' (returns from states)
*[[Return]] | '''D''' (returns from states)
*[[Break]] '''D''' (also breaks '''for''' and '''while*''' loops)
*[[Break]] | '''D''' (also breaks '''for''' and '''while*''' loops)
*[[Switch]]
*[[Switch]]
*[[Case]]
*[[Case]]
*[[Default]]
*[[Default]]
*[[Endswitch]]
*[[Endswitch]]
*[[Getcurraddress]] '''X'''
*[[Getcurraddress]] | '''X'''
*[[Jump]] '''X'''
*[[Jump]] | '''X'''


====struct access (redundant)====
====struct access (redundant)====
All of these are redundant, use "'''set''' ''xyz'' ''zyx''" instead.
These are inaccessible in newer versions of Mapster32, use "'''set''' ''xyz'' ''zyx''" instead.
*[[Setsector]]
<font color="grey">
*[[Getsector]]
*Setsector
*[[Setwall]]
*Getsector
*[[Getwall]]
*Setwall
*[[Setsprite]]
*Getwall
*[[Getsprite]]
*Setsprite
*[[Gettspr]] '''X'''
*Getsprite
*[[Settspr]] '''X'''
*Gettspr | '''X'''
*Settspr | '''X'''
</font>


====arrays====
====arrays====
*[[Gamearray]]
*[[Gamearray]]
*[[Setarray]] (redundant, use '''set''')
*[[Setarray]] | (redundant, use '''set''')
*[[Getarraysize]] ''array'' '''''size'''''
*[[Getarraysize]] ''array'' '''''size'''''
*[[Resizearray]] ''array'' ''newsize''
*[[Resizearray]] ''array'' ''newsize''
Line 62: Line 67:
*[[Orvar]]
*[[Orvar]]
*[[Xorvar]]
*[[Xorvar]]
*[[Shiftvarl]] (short: '''shiftl''')
*[[Shiftvarl]] | (short: '''shiftl''')
*[[Shiftvarr]] (short: '''shiftr''')
*[[Shiftvarr]] | (short: '''shiftr''')


====varvar commands====
====varvar commands====
*[[Randvarvar]]
*[[Randvarvar]]
*[[Displayrandvarvar]] (different from '''displayrand''')
*[[Displayrandvarvar]] | (different from '''displayrand''')
*[[Setvarvar]]
*[[Setvarvar]]
*[[Addvarvar]]
*[[Addvarvar]]
Line 79: Line 84:


====math commands====
====math commands====
The trigonometric commands interpret values outside the range [0, 2047] correctly as angles modulo 2048.
*[[Sin]] '''''resvar''''' ''var''
*[[Sin]] '''''resvar''''' ''var''
*[[Cos]] '''''resvar''''' ''var''
*[[Cos]] '''''resvar''''' ''var''
Line 85: Line 91:
*[[Clamp]] '''''var''''' ''min'' ''max''
*[[Clamp]] '''''var''''' ''min'' ''max''
*[[Sqrt]] ''var'' '''''resvar'''''
*[[Sqrt]] ''var'' '''''resvar'''''
*[[Mulscale]] ''factor1'' ''factor2'' ''rshiftamount''
*[[Mulscale]] '''''resvar''''' ''factor1'' ''factor2'' ''rshiftamount''
*[[Divscale]] '''''resvar''''' ''dividend'' ''divisor'' ''lshiftamount''
*[[Dist]] '''''res''''' ''sprite1'' ''sprite2''
*[[Dist]] '''''res''''' ''sprite1'' ''sprite2''
*[[Ldist]] '''''res''''' ''sprite1'' ''sprite2''
*[[Ldist]] '''''res''''' ''sprite1'' ''sprite2''
*[[Getangle]] '''''res''''' ''x'' ''y''
*[[Getangle]] '''''res''''' ''x'' ''y''
*[[Getincangle]] '''''res''''' ''ang1'' ''ang2''
*[[Getincangle]] '''''res''''' ''ang1'' ''ang2''
*[[A2xy]] ''angle'' '''''x''''' '''''y'''''
*[[Ah2xyz]] ''angle'' ''horiz'' '''''x''''' '''''y''''' '''''z'''''
*[[Calchypotenuse]] '''''hypot''''' ''x'' ''y''


====special commands====
====special commands====
*[[Sort]] '''''array''''' ''count'' [''comparison_state'']
*[[Sort]] '''''array''''' ''count'' [''comparison_state'']
*[[Collectsectors]] '''''array''''' ''count'' '''''numcollectedsectors''''' [''comparison_state'']
*[[For]] '''''itervar''''' ''what'' [''what2'']
*[[For]] '''''itervar''''' ''what'' [''what2'']
valid iteration types (''what''):<br>
valid iteration types (''what''):<br>
Line 98: Line 109:
*allsprites ('''i'''), allsectors, allwalls, selsprites ('''i'''), selsectors, selwalls, drawnsprites ('''s''', indexes tsprite[])
*allsprites ('''i'''), allsectors, allwalls, selsprites ('''i'''), selsectors, selwalls, drawnsprites ('''s''', indexes tsprite[])
*spritesofsector ''sector'' ('''i'''), loopofwall ''wall'', wallsofsector ''sector'', range ''num''
*spritesofsector ''sector'' ('''i'''), loopofwall ''wall'', wallsofsector ''sector'', range ''num''
=====examples=====
Using the '''for''' command you can create batch modifications in a few lines. (note: these examples don't claim to be useful)
*making liztroops really big
for i allsprites, ifactor LIZTROOP, sizeat 128 128
*translating the whole map by (x,y,z)
for i allsectors
{
    add sector[i].ceilingz z, add sector[i].floorz z
    for j wallsofsector i, { add wall[j].x x, add wall[j].y y }
    for j spritesofsector i, { add .x x, add .y y, add .z z }
}


====var if* and while* commands====
====var if* and while* commands====
Line 143: Line 168:
*[[Ifpdistl]] ''dist'' | '''S''' (distance is that of "mapper arrow" to current sprite)
*[[Ifpdistl]] ''dist'' | '''S''' (distance is that of "mapper arrow" to current sprite)
*[[Ifpdistg]] ''dist'' | '''S''' (distance is that of "mapper arrow" to current sprite)
*[[Ifpdistg]] ''dist'' | '''S''' (distance is that of "mapper arrow" to current sprite)
*[[Ifawayfromwall]] '''S'''
*[[Ifawayfromwall]] | '''S'''
*[[Ifcansee]] '''S''' (whether "mapper arrow" can see current sprite)
*[[Ifcansee]] | '''S''' (whether "mapper arrow" can see current sprite)
*[[Ifonwater]] '''S'''
*[[Ifonwater]] | '''S'''
*[[Ifinwater]] '''S'''
*[[Ifinwater]] | '''S'''
*[[Ifoutside]] '''S'''
*[[Ifoutside]] | '''S'''
*[[Ifaimingsector]]
*[[Ifaimingwall]]
*[[Ifaimingsprite]]
*[[Ifin3dmode]]
*[[Ifinteractive]]


====BUILD functions====
====BUILD functions====
*[[Insertsprite]] '''X''' '''i''' '''s'''
*[[Insertsprite]] | '''X''' '''i''' '''s'''
*[[Dupsprite]] ''oldsprite'' | '''i''' '''s'''
*[[Dupsprite]] ''oldsprite'' | '''i''' '''s'''
*[[Tdupsprite]] ''sprite'' | '''s''' (copies ''sprite'' to tsprite[''spritesortcnt''] and increments ''spritesortcnt'')
*[[Tdupsprite]] ''sprite'' | '''s''' (copies ''sprite'' to tsprite[''spritesortcnt''] and increments ''spritesortcnt'')
Line 173: Line 203:
*[[Changespritestat]] ''spritenum'' ''statnum''
*[[Changespritestat]] ''spritenum'' ''statnum''
*[[Changespritesect]] ''spritenum'' ''sectnum''
*[[Changespritesect]] ''spritenum'' ''sectnum''
*[[Headspritestat]] '''X'''
*[[Headspritestat]] | '''X'''
*[[Prevspritestat]] '''X'''
*[[Prevspritestat]] | '''X'''
*[[Nextspritestat]] '''X'''
*[[Nextspritestat]] | '''X'''
*[[Headspritesect]] '''X'''
*[[Headspritesect]] | '''X'''
*[[Prevspritesect]] '''X'''
*[[Prevspritesect]] | '''X'''
*[[Nextspritesect]] '''X'''
*[[Nextspritesect]] | '''X'''
*[[Sectorofwall]] ''wallnum''
*[[Sectorofwall]] ''wallnum''
*[[Fixrepeats]] ''wallnum''
*[[Fixrepeats]] ''wallnum''
The following returns a (positive) game palette index "closest" to the RGB color passed.
*[[Getclosestcol]] ''r'' ''g'' ''b'' '''''var'''''


====debugging commands====
====debugging commands====
Line 190: Line 222:
*[[Definequote]] ''quotenum'' [text...] | (initial definition of a quote)
*[[Definequote]] ''quotenum'' [text...] | (initial definition of a quote)
*[[Redefinequote]] ''quotenum'' [text...] | (replacement occurs at runtime)
*[[Redefinequote]] ''quotenum'' [text...] | (replacement occurs at runtime)
*[[Print]] ''quotenum'' | (prints to the OSD)
*[[Quote]] ''quotenum''
*[[Quote]] ''quotenum''
*[[Error]] ''quotenum''
*[[Error]] ''quotenum''
*[[Printmessage16]] ''quotenum''
*[[Printmessage16]] ''quotenum'' | 2D mode only
*[[Printmessage256]] ''quotenum'' ''x'' ''y'' ''col'' ''backcol'' ''fontsize''
*[[Printmessage256]] ''quotenum'' ''x'' ''y'' | 3D mode only
*[[Printext256]] ''quotenum'' ''x'' ''y'' ''col'' ''backcol'' ''fontsize''
*[[Printext256]] ''quotenum'' ''x'' ''y'' ''color'' ''backcolor'' ''fontsize'' | 3D mode only, -''color'' is looked up in ''editorcolors'' if ''color'' is negative
*[[Printext16]] ''quotenum'' ''x'' ''y'' ''col'' ''backcol'' ''fontsize''
*[[Printext16]] ''quotenum'' ''x'' ''y'' ''color'' ''backcolor'' ''fontsize'' | 2D mode only, color is looked up in ''editorcolors''
Specifying a negative ''max'' argument will make the allowable number range be ''max'' to -''max'':
*[[Drawlabel]] ''quotenum'' ''x'' ''y'' ''color'' ''backcolor'' ''fontsize'' | Draws a small label. 2D mode only; build units.
*[[Getnumber16]] '''''var''''' ''quotenum'' ''max''
 
*[[Getnumber256]] '''''var''''' ''quotenum'' ''max''
The following two commands query the user for a number from 0 to ''max'',
specifying a negative ''max'' argument will make the allowable number range be ''max'' to -''max'': (deprecated)
*[[Getnumber16]] '''''var''''' ''quotenum'' ''max'' | '''X'''
*[[Getnumber256]] '''''var''''' ''quotenum'' ''max'' | '''X'''
*[[Getnumberfromuser]] '''''var''''' ''quotenum'' ''max'' ''flags''
Valid ''flags'' are:
 
: 1: sign  (allow values from -''max'' to ''max'')<br/>
: 2: autocomplete names<br/>
: 4: autocomplete taglabels<br/>
: 8: return -1 if cancelled. Otherwise, the initial value is returned, which is the one passed in '''''var'''''.
*[[Qsprintf]] '''''destquote''''' ''srcquote'' [up to 32 arguments...]
*[[Qsprintf]] '''''destquote''''' ''srcquote'' [up to 32 arguments...]
*[[Qstrcat]] '''''destquote''''' ''srcquote''
*[[Qstrcat]] '''''destquote''''' ''srcquote''
Line 218: Line 261:
*[[Gettimedate]] (8 arguments...)
*[[Gettimedate]] (8 arguments...)
*[[Setaspect]] ''viewingrange'' ''yxaspect''
*[[Setaspect]] ''viewingrange'' ''yxaspect''
*[[Sethighlight]] ''what'' ''sprite_or_wall_num'' ''set?''
: If ''what'' has bit 16384 set, the lower 14 bits of ''sprite_or_wall_num'' are taken as sprite index, else wall index
*[[Sethighlightsector]] ''sectnum'' ''set?''


====current sprite commands====
====current sprite commands====
Line 227: Line 273:
*[[Spritepal]] ''palnum'' | '''S'''
*[[Spritepal]] ''palnum'' | '''S'''
*[[Cactor]] ''picnum'' | '''S'''
*[[Cactor]] ''picnum'' | '''S'''
*[[Spgetlotag]] '''S'''
*[[Spgetlotag]] | '''S'''
*[[Spgethitag]] '''S'''
*[[Spgethitag]] | '''S'''
*[[Sectgetlotag]] '''S'''
*[[Sectgetlotag]] | '''S'''
*[[Sectgethitag]] '''S'''
*[[Sectgethitag]] | '''S'''
*[[Gettexturefloor]] '''S'''
*[[Gettexturefloor]] | '''S'''
*[[Gettextureceiling]] '''S'''
*[[Gettextureceiling]] | '''S'''


====drawing commands====
====drawing commands====
The suffixes 16 and 256 mean that the commands are to be used in 2D and 3D modes, respectively.
======used in EVENT_DRAW2DSCREEN======
======used in EVENT_DRAW2DSCREEN======
*[[Drawline16]] ''x1'' ''y1'' ''x2'' ''y2'' ''col''
*[[Drawline16]] ''x1'' ''y1'' ''x2'' ''y2'' ''color''
*[[Drawline16b]] ''x1'' ''y1'' ''x2'' ''y2'' ''col'' (BUILD units)
*[[Drawline16b]] ''x1'' ''y1'' ''x2'' ''y2'' ''color'' | (coordinates are in BUILD units)
*[[Drawcircle16]] ''x'' ''y'' ''radius''
*[[Drawline16z]] ''x1'' ''y1'' ''z1'' ''x2'' ''y2'' ''z2'' ''color'' | (coordinates are in BUILD units)
*[[Drawcircle16b]] ''x'' ''y'' ''radius'' (BUILD units)
*[[Drawcircle16]] ''x'' ''y'' ''radius'' ''color''
*[[Drawcircle16b]] ''x'' ''y'' ''radius'' ''color'' | (coordinates are in BUILD units)
*[[Drawcircle16z]] ''x'' ''y'' ''z'' ''radius'' ''color'' | (coordinates are in BUILD units)
Specifying nonnegative values for the color will use the 16-color editor palette, whereas negative values -1 to -255 will use a palette of all colors available in 2D mode, where the palette is the base game palette.
 
======used elsewhere======
======used elsewhere======
*[[Rotatesprite16]]
*[[Rotatesprite16]]
Line 255: Line 306:
*[[Globalsound]] ''sound#''
*[[Globalsound]] ''sound#''
*[[Stopallsounds]]
*[[Stopallsounds]]
[[Category:Level editing documentation]]

Revision as of 17:38, 5 August 2020

Build/Mapster32 Map Editing
Mapster32 Scripting

This is a categorized list of every command in Mapster32-script.

Legend:
I: acts on current sprite, S: acts on current sprite by pointer (also valid in "for i drawnsprites")
i: sets current sprite, s: only sets current sprite by pointer
D: differs from CON, X: deprecated/do not use (yet)
var/array/special: must be writable, [something]: optional command field

A note on the current sprite: when the current sprite index I is set (that is, greater or equal zero), all functions that act on sprites by pointer (S) are also available since the sprite pointer is set to point to the sprite[] array at index I in this case. The converse is not true, however: the sprite pointer could be set to a sprite structure other than the main sprite[] array (such as the tsprite[] array of sprites drawn on the screen), so code in a scope where the sprite pointer has been set (s) cannot use functions accessing the sprite[] array (I).

basic commands

control flow

struct access (redundant)

These are inaccessible in newer versions of Mapster32, use "set xyz zyx" instead.

  • Setsector
  • Getsector
  • Setwall
  • Getwall
  • Setsprite
  • Getsprite
  • Gettspr | X
  • Settspr | X

arrays

var commands

varvar commands

math commands

The trigonometric commands interpret values outside the range [0, 2047] correctly as angles modulo 2048.

special commands

  • Sort array count [comparison_state]
  • Collectsectors array count numcollectedsectors [comparison_state]
  • For itervar what [what2]

valid iteration types (what):
Note: where the current sprite is affected, it is restored at the end of the loop

  • allsprites (i), allsectors, allwalls, selsprites (i), selsectors, selwalls, drawnsprites (s, indexes tsprite[])
  • spritesofsector sector (i), loopofwall wall, wallsofsector sector, range num
examples

Using the for command you can create batch modifications in a few lines. (note: these examples don't claim to be useful)

  • making liztroops really big
for i allsprites, ifactor LIZTROOP, sizeat 128 128
  • translating the whole map by (x,y,z)
for i allsectors
{
   add sector[i].ceilingz z, add sector[i].floorz z
   for j wallsofsector i, { add wall[j].x x, add wall[j].y y }
   for j spritesofsector i, { add .x x, add .y y, add .z z }
}

var if* and while* commands

varvar if* and while* commands

other if* commands

BUILD functions

The following returns a (positive) game palette index "closest" to the RGB color passed.

debugging commands

quote commands

  • Definequote quotenum [text...] | (initial definition of a quote)
  • Redefinequote quotenum [text...] | (replacement occurs at runtime)
  • Print quotenum | (prints to the OSD)
  • Quote quotenum
  • Error quotenum
  • Printmessage16 quotenum | 2D mode only
  • Printmessage256 quotenum x y | 3D mode only
  • Printext256 quotenum x y color backcolor fontsize | 3D mode only, -color is looked up in editorcolors if color is negative
  • Printext16 quotenum x y color backcolor fontsize | 2D mode only, color is looked up in editorcolors
  • Drawlabel quotenum x y color backcolor fontsize | Draws a small label. 2D mode only; build units.

The following two commands query the user for a number from 0 to max, specifying a negative max argument will make the allowable number range be max to -max: (deprecated)

Valid flags are:

1: sign (allow values from -max to max)
2: autocomplete names
4: autocomplete taglabels
8: return -1 if cancelled. Otherwise, the initial value is returned, which is the one passed in var.

findnear* (not tested)

misc. commands

If what has bit 16384 set, the lower 14 bits of sprite_or_wall_num are taken as sprite index, else wall index

current sprite commands

drawing commands

The suffixes 16 and 256 mean that the commands are to be used in 2D and 3D modes, respectively.

used in EVENT_DRAW2DSCREEN

Specifying nonnegative values for the color will use the 16-color editor palette, whereas negative values -1 to -255 will use a palette of all colors available in 2D mode, where the palette is the base game palette.

used elsewhere

sound commands

All sound commands accept vars. Sounds should appear from current sprite if set and globally otherwise (not tested).