MappyWin32 Lua scripting documentation


 Lua scripts. Added in 1.3.22, you can write scripts to perform functions in the editor such as exporting/importing graphics, maps and other data from custom formats, editing the map or blocks, performing a custom task and many other things. The scripts are written in a language called LUA (see www.lua.org), see the copyright notice in the luascr folder. Lua scripts can either be put in the luascr folder, and then set the LUA values in the mapwin.ini file to add them to the Custom menu. Alternatively, you can drag and drop a file ending with '.lua' onto MappyWin32 to run it.

 I'd like to thank Robbob (Autofringe, Random distribution) and Jerzy Kut (Export binary file) for their help with lua. I have included some example scripts in the luascr folder (not all of these are listed in the custom menu), look at them in a text editor to see how they work, I am a novice with Lua, so they are quite basic. Load a test map and run them to see what they do, most of them give a brief summary of what they do before they start. You do not need to restart Mappy if you modify a script. You can override the functions in the file menu with lua scripts to fully customize loading and saving of maps (see mapwin.ini). MappyWin32 extends LUA with these functions (don't forget to prefix functions and values with 'mappy.' see the .lua files in the luascr folder):

General functions:
R = getValue (VALUE_ID)
 where VALUE_ID is one of:
MAPWIDTH, MAPHEIGHT, BLOCKDEPTH, BLOCKWIDTH, BLOCKHEIGHT, NUMBLOCKSTR, NUMBLOCKGFX, BLOCKGAPX, BLOCKGAPY, BLOCKSTAGGERX, BLOCKSTAGGERY, CLICKMASK, TRANS8, TRANSRED, TRANSGREEN, TRANSBLUE, CURLAYER, CURBLOCK, CURANIM, CURBRUSH, MOUSEBLOCKX, MOUSEBLOCKY, GETBLOCKMODE, PALETTEARGB+index, NUMBLOCKANIM, XMAPOFFSET, YMAPOFFSET, MAPFILENAME, MAPWINPATH, MAPTYPE, MAPWINVERSION, NUMBRUSHES, NUMLAYERS, CUROBJECT, NUMOBJECTS, CMDLINE, NUMCHUNKS, CURGFX

setValue (VALUE_ID, SETVALUE)
 where VALUE_ID is one of:
TRANS8, TRANSRED, TRANSGREEN, TRANSBLUE, PALETTEARGB+index, GETBLOCKMODE, CURLAYER, CURBLOCK, CURANIM, CURBRUSH, XMAPOFFSET, YMAPOFFSET, MAPFILENAME, CUROBJECT, MAPTYPE, CURGFX

R = shiftVal (VALUE, SHIFT) negative shift is left, positive is right
R = andVal (VALUE1, VALUE2)
R = orVal (VALUE1, VALUE2)

Block functions:
R = getBlock (X, Y [,L])
 where X is the x coord in blocks, and Y is y coord in blocks, L is the optional layer number, omit it for current layer

setBlock (X, Y, B [,L])
 where X is the x coord in blocks, and Y is y coord in blocks, and B is the block index, L is the optional layer number, omit it for current layer (see 'Solid rectangle.lua' for an example)

R = getBlockValue (B, VALUE_ID)
 where B is the block index, and VALUE_ID is one of:
BLKBG, BLKFG1, BLKFG2, BLKFG3, BLKUSER1, BLKUSER2, BLKUSER3, BLKUSER4, BLKUSER5, BLKUSER6, BLKUSER7, BLKFLAG1, BLKFLAG2, BLKFLAG3, BLKFLAG4, BLKFLAG5, BLKFLAG6, BLKFLAG7, BLKFLAG8

setBlockValue (B, VALUE_ID, VALUE)
 where B is the block index, and VALUE_ID is one of:
BLKBG, BLKFG1, BLKFG2, BLKFG3, BLKUSER1, BLKUSER2, BLKUSER3, BLKUSER4, BLKUSER5, BLKUSER6, BLKUSER7, BLKFLAG1, BLKFLAG2, BLKFLAG3, BLKFLAG4, BLKFLAG5, BLKFLAG6, BLKFLAG7, BLKFLAG8
and VALUE is the value to write (flags are 0 or 1) see 'Tile graphic test.lua'

createBlock (B)
 where B is the block index to insert the new block at

deleteBlock (B)
 where B is the block index to remove
R = getBlockSort (index)
Gets the block number from the sortlist
setBlockSort (index, B)
If sortblocks=1 in mapwin.ini, the script luascr/BlockSort.lua is called when the Blocks in the Block Editor window are refreshed. You can filter blocks however you want, and put the blocks you want to display in the list



Layer functions:
copyLayer (SOURCE, DEST)
  where SOURCE is the layer to copy from (0 to 7 or MPY_UNDO), and DEST is the layer to copy to (0 to 7 or MPY_UNDO) if you are changing the current layer, use:
mappy.copyLayer(mappy.getValue(mappy.CURLAYER),mappy.MPY_UNDO)
to enable undo.

createLayer (layer)
deleteLayer (layer)

Graphics functions:
createGraphic (G)
 where G is the graphic index to insert the new graphic at

deleteGraphic (G)
 where G is the graphic index to remove

In the following A is Alpha, R is Red, G is Green, B is Blue, all values between 0 (none) and 255 (max), 0 Alpha is transparent, 255 is solid.
A,R,G,B = getPixel (X, Y, G)
 where X, Y is pixel coord within the graphic, G is the graphic index

setPixel (X, Y, G, A, R, G, B) or
setPixel (X, Y, G, INDEX)
 where INDEX is the palette index 0 to 255)

R = importGraphics ("FILENAME", GFXPOS, AMOUNT)
  where GFXPOS is the graphic number to start importing at, and AMOUNT is the number of tiles to import. AMOUNT can be 0 for all.

Dialogue/Requester functions:
R = msgBox ("TITLE", "MESSAGE", TYPE, ICON)
 where TYPE is one of:
MMB_OK, MMB_OKCANCEL, MMB_YESNOCANCEL,
and ICON is one of:
MMB_ICONNONE, MMB_ICONINFO, MMB_ICONQUESTION, MMB_ICONEXCLAMATION
returns one of:
MMB_CANCEL, MMB_YES, MMB_NO

R, "FILENAME" = fileRequester ("PATH", "DESCRIPTION", "EXTENSION", TYPE)
 where PATH is the starting folder (try "."), DESCRIPTION is what appears in the 'Save as type' box, EXTENSION is a properly formatted mask for file extensions (ie: "*.FMP" or "*.FMP;*.MAP"). And TYPE is either MMB_OPEN or MMB_SAVE
returns R, either MMB_OK or MMB_CANCEL, also "FILENAME"

R = doDialogue ("TITLE", "MESSAGE", "STRING", TYPE)
 where TYPE is either MMB_DIALOGUE1 or MMB_DIALOGUE2, type 1 returns MMB_OK or MMB_CANCEL and one string, type 2 returns MMB_OK or MMB_CANCEL and as many strings as there were commas plus 1 (ie: hello,1,2,3 would return four strings "hello" "1" "2" and "3")
Complex dialogue boxes:
R = doDialogue ("DLGPROC")
  "DLGPROC" is the name of the handler for dialogue messages. See the scripts 'Dialogue Example.lua' and 'Dialogue Proc.lua'. Some knowledge of Win32 dialogues is required.
createDialogue ("Title", STYLE, X, Y, W, H, NUMCONTROLS)
  creates a custom dialogue, STYLE can be 0 for default. See the scripts 'Dialogue Example.lua' and 'Dialogue Proc.lua'. Some knowledge of Win32 dialogues is required.
addDialogueItem ("Title", STYLE, X, Y, W, H, IDC, TYPE)
  See defines in 'Dialogue Example.lua'
hwnd, msg, wParam, lParam = getDialogueParam ()
  See 'Dialogue Proc.lua', note: Proc is sent idc == 99 on creation so lists can be populated and labels changed etc
checkDlgButton (IDC, STATUS)
  Sets button IDC to STATUS
R = isDlgButtonChecked (IDC)
  R is STATUS of button IDC
R = getDlgItemText (IDC)
  R is text of item as a string
setDlgItemText (IDC, "TEXT")
  TEXT is new text of item as a string
R = sendDlgItemMessage (IDC, MSG, WPARAM, LPARAM)
  Get and Set information for all types of buttons etc. Allows setting and retrieving see any tutorial on Win32 dialogues and DlgItemMessage


Anim functions:
createAnim (animnum)
deleteAnim (animnum)
R = getAnimFrame (animnum, framenum)
'framenum' can be ANMREFFRAME
setAnimFrame (animnum, framenum, blockval)
'framenum' can be ANMREFFRAME
R = numAnimFrames (animnum)
insertAnimFrame (animnum, framenum, blockval)
cutAnimFrame (animnum, framenum)
R = numAnimFrames (animnum)
R = getAnimValue (VAL)
VAL is:
ANMDELAY, ANMCOUNT, ANMTYPE, ANMUSER, ANMCURFRAME
setAnimValue (VAL, val)
VAL is:
ANMDELAY, ANMCOUNT, ANMTYPE, ANMUSER, ANMCURFRAME

Brush functions:
createBrush (brshnum, x, y, w, h)
deleteBrush (brshnum)
renameBrush (brshnum, "Brushname")
R = getBrushBlock (brshnum, x, y)
setBrushBlock (brshnum, x, y, blk)
R = getBrushValue (VAL)
VAL is:
BRUSHWIDTH, BRUSHHEIGHT, BRUSHNAME

TextString functions:
getTextString (index)
setTextString (index, "Text")

Map/System functions:
newMap (mapwidth, mapheight, mapdepth, tilewidth, tileheight, [tilegapx, tilegapy, tilestaggerx, tilestaggery, maptype])
closeMap ()
openFMP (["FILENAME"])
saveFMP (["FILENAME"])
  if no "filename" supplied, current filename is used. On saving, use mappy.setValue(mappy.MAPFILENAME, "filename") if you want to change the name
resizeMap (WIDTH, HEIGHT, CENTERING)
  CENTERING is from 1 to 9 as in the MapTools:Resize dialogue
updateScreen ()
  call this to refresh the display after altering a layer

shellExecute (action, file, params, dir, style)
  call an external programme, example: mappy.shellExecute ("open", "notepad", "mapwin.ini", "c:/mapwin148/", 0)
sendMessage (code, 0)
code is one of the key shortcuts listed in mapwin.htm
for example sendMessage (119, 0) shows the helpfile
renameMenuItem (code, "Name")
  code is one of the key shortcuts listed in mapwin.htm. "Name" is the new name for the menu item
moveWindow (WINDOW, x, y, width, height)
  added (WINDOW = MPY_MAINWINDOW, MPY_MAPWINDOW or MPY_BLOCKWINDOW)

Object functions (Pro only):
createObject (position)
deleteObject (objnum)
R = getObjectValue (objnum, VALUE_ID)
setObjectValue (objnum, VALUE_ID, objval)
VALUE_ID for the above can be one of: OBJXPOS, OBJYPOS, OBJGFXID, OBJTILEID, OBJGXOFF, OBJGYOFF, OBJGWIDTH, OBJGHEIGHT, OBJGHANDLEXOFF, OBJGHANDLEYOFF, OBJSHOW, OBJUSER1, OBJUSER2, OBJUSER3, OBJUSER4, OBJUSER5, OBJUSER6, OBJUSER7, OBJFLAGS
R = getObjectFilename (index)
Gets the string for the image filename displayed in the Object Properties dialogue, 'index' is the position in the list
setObjectFilename (index, "Filename")
Sets the string for the image filename displayed in the Object Properties dialogue, 'index' is the position in the list
R = getObjectSort (index)
Gets the object number from the sortlist
setObjectSort (index, objnum)
If sortobjects=1 in mapwin.ini, the script luascr/ObjectSort.lua is called when the Objects in the Block Editor window are refreshed. You can filter objects however you want, and put the objects you want to display in the list

Chunk functions:
Warning: for custom chunks only, incorrect use can corrupt map file
createChunk ("CHNK", size, position)
  "CHNK" is a four character string NOT used by the editor, size is the size of the chunk in bytes, position is where in custom chunks it is inserted (use 0 to put it at the front)
deleteChunk (chunknum)
R = getChunkValue (chunknum, offset)
setChunkValue (chunknum, offset, value)

(top of doc)

(Back to main documentation)