Lunatic: allow access to sprite[].yvel through set_yvel() member, document.

BUILD_LUNATIC.

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

polymer/eduke32/source/lunatic/con_lang.lua

@@ -380,7 +380,7 @@ local ActorLabels = {
     ang = SP".ang",
     owner = { SP".owner", SP":_set_owner(%%s)", litok_ge0 },
     xvel = SP".xvel",
-    yvel = { SP".yvel", SP":_set_yvel(%%s)" },  -- XXX
+    yvel = { SP".yvel", SP":set_yvel(%%s)" },
     zvel = SP".zvel",
     lotag = SP".lotag",
     hitag = SP".hitag",

polymer/eduke32/source/lunatic/control.lua

@@ -1058,7 +1058,7 @@ function _debris(i, dtile, n)
                                  shade=spr.shade, xrepeat=32+krandand(15), yrepeat=32+krandand(15),
                                  ang=krandand(2047), xvel=32+krandand(127), zvel=-krandand(2047) }
         -- NOTE: BlimpSpawnSprites[14] (its array size is 15) will never be chosen
-        sprite[jj]:_set_yvel(isblimpscrap and ffiC.BlimpSpawnSprites[math.mod(jj, 14)] or -1)
+        sprite[jj]:set_yvel(isblimpscrap and ffiC.BlimpSpawnSprites[math.mod(jj, 14)] or -1)
         sprite[jj].pal = spr.pal
     end
 end
@@ -1715,7 +1715,7 @@ function _G_OperateMasterSwitches(tag)
     for i in spritesofstat(STAT.STANDABLE) do
         local spr = sprite[i]
         if (ispic(spr.picnum, "MASTERSWITCH") and spr.lotag==tag and spr.yvel==0) then
-            spr:_set_yvel(1)
+            spr:set_yvel(1)
         end
     end
 end

polymer/eduke32/source/lunatic/defs_common.lua

@@ -671,6 +671,11 @@ local tspritetype_ptr_ct = ffi.typeof("$ *", ffi.typeof("tspritetype"))
 
 local intarg = ffi.new("int32_t[1]")
 
+-- XXX: We ought to be using the dynamic value, but users remapping that tile
+-- are likely somewhat confused anyway. Also, it would be more proper if this
+-- lived on game-side Lunatic.
+local APLAYER = 1405
+
 local spritetype_mt = {
     __pow = function(s, zofs)
         return vec3_ct(s.x, s.y, s.z-zofs)
@@ -679,15 +684,18 @@ local spritetype_mt = {
     __index = {
         --- Setters
         set_picnum = function(s, tilenum)
+            if (s.picnum == APLAYER or tilenum == APLAYER) then
+                error("setting picnum to or on an APLAYER sprite forbidden")
+            end
             check_tile_idx(tilenum)
             ffi.cast(spritetype_ptr_ct, s).picnum = tilenum
         end,
 
-        _set_yvel = function(s, yvel)
-            -- XXX: no protection against malicious use (might set picnum to
-            -- another one temporarily)
-            -- XXX: this belongs into game-side Lunatic
-            if (s.picnum==1405) then  -- APLAYER
+        set_yvel = function(s, yvel)
+            -- XXX: A malicious user might still find some backdoor way to
+            --  inject a bad yvel value, but this together with the above
+            --  set_picnum() check should at least prevent naive attempts.
+            if (s.picnum == APLAYER) then
                 error("setting yvel on an APLAYER sprite forbidden", 2)
             end
             ffi.cast(spritetype_ptr_ct, s).yvel = yvel

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

@@ -859,8 +859,9 @@ For actors and other moving sprite kinds, the horizontal and vertical
 components of the current velocity. See the description of
 <<con_move,`con.move`>> for more details.
 
-//`yvel` (read-only)::
-//A general-purpose member of which the game has exclusive control.
+_`i16`_ `yvel` (read-only)::
+A member used for different purposes by Duke3D. Setting it is only allowed
+through the `set_yvel` method.
 
 _`i16`_ `lotag`, `hitag`, `extra`::
 General-purpose ``tags'' provided for game programming. They may be used by
@@ -870,7 +871,13 @@ claiming them for oneself.
 ===== `sprite` methods
 
 `spr:set_picnum(tilenum)`::
-Sets the tile number of sprite `spr` to `tilenum`.
+Sets the tile number of sprite `spr` to `tilenum`. It is disallowed to issue
+`set_picnum` on an `APLAYER` sprite or change the tile number of a sprite to
+`APLAYER`.
+
+`spr:set_yvel(yvel)`::
+Sets the `yvel` member of sprite `spr` to `yvel`. It is disallowed to issue
+`set_yvel` on an `APLAYER` sprite. Further restrictions are reserved.
 
 `spr:getheightofs()` -> `height`, `offset`::
 Returns the `height` and z `offset` of sprite `spr` in BUILD z units. Adding the