Lunatic: document engine.*shadetab() functions. DONT_BUILD.

git-svn-id: https://svn.eduke32.com/eduke32@4262 1a8010ca-5511-0410-912e-c29ae57300e0

polymer/eduke32/source/lunatic/defs.ilua

@@ -1540,7 +1540,6 @@ function gv_access._set_guniqhudid(id)
     ffiC.guniqhudid = id
 end
 
--- TODO: make return 1-based index?
 function gv_access.currentEpisode()
     return ffiC.ud.volume_number + 1
 end

polymer/eduke32/source/lunatic/doc/lunatic.txt

@@ -345,6 +345,17 @@ The maximum permissible weapon index plus one.
 TODO
 //////////
 
+`gv.LUNATIC_CLIENT`::
+
+A constant indicating which program Lua is embedded into. It can be compared
+for (in)equality with:
++
+* `gv.LUNATIC_CLIENT_EDUKE32`
+* `gv.LUNATIC_CLIENT_MAPSTER32`
++
+(Mapster32 supports a subset of Lunatic that is not documented and subject to
+change at any time.)
+
 Variables
 ^^^^^^^^^
 
@@ -2111,6 +2122,64 @@ respect to how pixels of objects farther away are drawn. For example:
   latexmath:[$i$] are achieved by setting palookup[sh][latexmath:[$i$]] to
   palookup[0][latexmath:[$i$]] for each shade sh.
 
+===== Shade table functions
+
+`sht = engine.shadetab()`::
+
+Creates and returns a new shade table object `sht` with all entries initialized
+to zero. This object can be indexed once with a shade index from 0 to 31,
+yielding a reference to an array of 256 8-bit unsigned integers. Thus, shade
+table objects can be used just as indicated in the notation above: `sht[sh][i]`
+is the resulting color index for shade `sh` and input color index `i`.
+
+`sht = engine.getshadetab(palnum)`::
+
+Returns a new shade table object `sht` containing the values for the palookup
+table of pal `palnum`, provided it is not an alias for the default one (see
+below). Modifying the returned `sht` does not alter the actual engine-side
+shade table. An unspecified number of pal indices are reserved from the end of
+the hard limit 255; attempting to retrieve a shade table for a reserved pal
+raises as error.
++
+At engine initialization, the shade tables for all non-zero pal numbers are
+aliased to the default pal 0 one. Subsequently, custom palookup tables are
+either loaded from LOOKUP.DAT, created by appropriate DEF directives (`fogpal`
+or `makepalookup`), or assigned using `engine.setshadetab`. If the table for
+pal `palnum` is aliased to the default one when `getshadetab` is called, *nil*
+is returned.
+
+`engine.setshadetab(palnum, sht)`::
+
+Copies the shade table `sht` to the engine-side palookup table for pal
+`palnum`. An error is issued if an attempt is made to copy to a reserved
+`palnum`.
++
+When running in EDuke32, there are additional restrictions:
++
+* A `palnum` for which a shade table has already been registered (that is, one
+  which is *not* aliased to the default one) cannot be re-assigned to.
++
+* `setshadetab` may only be called at first initialization time, that is, when
+  the value of `LUNATIC_FIRST_TIME` is *true*. (`LUNATIC_FIRST_TIME` is a
+  variable in the global environment that indicates whether the Lua game state
+  is created for the very first time and the game is not yet running.)
+
+//////////
+===== Shade table methods
+
+`newsht = sht:remap16(tab)`::
+
+Rearranges consecutive runs of 16 values of every shade 256-tuple of `sht` by
+the 0-based selection given by the 0-based sequence `tab`.
++
+.Example
+[source]
+----------
+local perm16 = { [0]=0,1, 2,3, 5,4, 6,7, 8,13, 10,11, 12,9, 14,15 }
+local newsht = engine.getshadetab(0):remap16(perm16)
+----------
+//////////
+
 
 The `fs` module -- virtual file system facilities
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

polymer/eduke32/source/lunatic/engine.lua

@@ -83,7 +83,7 @@ engine.RESERVEDPALS = RESERVEDPALS
 
 local function check_palidx(i)
     if (type(i) ~= "number" or not (i >= 0 and i <= 255-RESERVEDPALS)) then
-        error("invalid argument #1: palette index must be in the range [0 .. "..255-RESERVEDPALS.."]", 3)
+        error("invalid argument #1: palette swap index must be in the range [0 .. "..255-RESERVEDPALS.."]", 3)
     end
 end
 

polymer/eduke32/source/lunatic/test.lua

@@ -88,8 +88,6 @@ gameevent
                 sprite[spr].pal = 6
             end
 
-            --this is a problem
-            --actor = {}
             actor[562].flags = bit.bor(actor[562].flags, 2);   -- pal 6 with goggles on front SEENINE
         end
 ---[[
@@ -173,6 +171,8 @@ gameevent
 
         checkfail("require('engine').setshadetab(200, nil)",
                   "setshadetab() may be run only while LUNATIC_FIRST_TIME is true")
+
+        checkfail("sprite[0]:set_picnum(-10)", "invalid tile number")
     end
 }
 
@@ -193,6 +193,9 @@ checkfail('print(sprite._nextspritesect[4].whatfield)', "attempt to index a numb
 
 -- gamevars are created using a special different mechanism
 checkfail("new_global = 345", "attempt to write into the global environment")
+-- Can't reassign to existing vars either
+assert(actor ~= nil)
+checkfail("actor = 345", "attempt to write into the global environment")
 
 -- can't redefine constants in 'gv'
 checkfail('gv.CEILING = 3', "attempt to write to constant location")
@@ -223,7 +226,6 @@ checkfail("do local bt=require'test.test_bitar'; bt.QWE=1; end", "modifying modu
 -- the cdata returned by player[] can't be made into a pointer!
 checkfail("do local pl=player[0]; i=pl[1]; end")
 checkfail("do local ud=gv.ud.camerasprite; end", "access forbidden")  -- test for proper decl()
-checkfail("sprite[0]:set_picnum(-10)", "invalid tile number")
 checkfail("gv.g_sizes_of=nil; print(gv.g_sizes_of[0])", "write access forbidden")
 checkfail("gv.cam.sect=-1", "invalid sector number")
 checkfail("local flag=gv.SFLAG_NULL", "missing declaration")

polymer/eduke32/source/lunatic/test/shadexfog.lua

@@ -160,7 +160,7 @@ local function create_base_shtab_2(basesht)
     local basesht = basesht or engine.getshadetab(0)
 
     local perm16 = { [0]=0,1, 2,3, 5,4, 6,7, 8,13, 10,11, 12,9, 14,15 }
-    local sht = engine.shadetab():remap16(perm16)
+    basesht = basesht:remap16(perm16)
 
     local iperm16 = {}
     for i=0,15 do
@@ -177,6 +177,8 @@ local function create_base_shtab_2(basesht)
         baseidx[i] = i < 192 and 32*floor(i/32) or 16*floor(i/16)
     end
 
+    local sht = engine.shadetab()
+
     for sh=0,31 do
         for i=0,255-16 do
             local bi = baseidx[i]