From bfd9feb5aa03ba0e3517543ab6b90aeaef09e1bc Mon Sep 17 00:00:00 2001 From: helixhorned Date: Sat, 22 Jun 2013 11:31:12 +0000 Subject: [PATCH] Lunatic: document vector types, add forgotten warning icon. git-svn-id: https://svn.eduke32.com/eduke32@3895 1a8010ca-5511-0410-912e-c29ae57300e0 --- .../lunatic/doc/icons/din_w_crushing.png | Bin 0 -> 4811 bytes .../eduke32/source/lunatic/doc/lunatic.txt | 194 +++++++++++++++--- .../source/lunatic/test/rotfixed_actor.con | 8 + 3 files changed, 176 insertions(+), 26 deletions(-) create mode 100644 polymer/eduke32/source/lunatic/doc/icons/din_w_crushing.png diff --git a/polymer/eduke32/source/lunatic/doc/icons/din_w_crushing.png b/polymer/eduke32/source/lunatic/doc/icons/din_w_crushing.png new file mode 100644 index 0000000000000000000000000000000000000000..d402e7845f1cc9a9293ec3a6a84335b42a351d04 GIT binary patch literal 4811 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 @@ -468,7 +486,7 @@ If `cf.stat` has bit `sector.STAT.SLOPE` set, the tangent of the slope angle multiplied by 4096. Positive values make the ceiling or floor slope towards the floor, negative ones slope upward. -_`i32`_ `cf.z`:: +[[cf_z]] _`i32`_ `cf.z`:: The BUILD z coordinate (scaled by 16 compared to the x and y directions) of the pivoting line of the ceiling or floor. @@ -511,6 +529,7 @@ These name single bits: `FLIP_BITMASK`, `ORIENT_BITMASK`, `TRANS_BITMASK`. ''' +[[wall]] ===== `wall` Accessible from `0` to `gv.numwalls-1`. Each element has the following members: @@ -518,6 +537,10 @@ members: `x`, `y`:: The 2D coordinates or this wall point. Should not be set directly. +`z` (read-only):: +Always yields `0`. The primary purpose of this field is to make wall references +permissible as arguments to <> operations. + `point2` (read-only):: The index of the second wall point. @@ -530,7 +553,7 @@ For walls constrained by TROR extension, the upper and lower neighbor walls, respectively. Any of them may be `-1`, meaning that the wall is not attached to a neighbor in this direction. -[[wall_cstat]] _`u16`_ `cstat`, _`bitfield`_ `cstatbits`:: +[[wall_cstat]] _`u16`_ `cstat`, {nbsp} _`bitfield`_ `cstatbits`:: A bit field holding various flags about how the wall shoud be displayed, how collision detection should be handled, etc. The <> @@ -604,7 +627,7 @@ _`i16`_ `ang`:: TODO (make set_ang() out of that which always ANDs with 2047?) ////////// -[[sprite_cstat]] _`u16`_ `cstat`, _`bitfield`_ `cstatbits`:: +[[sprite_cstat]] _`u16`_ `cstat`, {nbsp} _`bitfield`_ `cstatbits`:: A bit field holding various flags about how the sprite shoud be displayed, how collision detection should be handled, etc. The <> @@ -682,10 +705,11 @@ Allows to manually change the status number of the sprite with index `i` to ===== `sprite` overridden operators -`spr^zofs`:: -Returns an `xmath.vec3` object that is the position of this sprite, diminished -by `zofs` in the z direction. Because in BUILD, z coordinates increase toward -the floor, the `^` can be thought of as ``raise the sprite by `zofs` units''. +[[sprite_power]] `spr^zofs`:: +Returns an <> object that contains the position of +this sprite, diminished by `zofs` in the z direction. Because in BUILD, z +coordinates increase toward the floor, the `^` can be thought of as ``raise the +sprite by `zofs` units''. ===== `sprite` static data @@ -823,11 +847,15 @@ input arguments: `func(aci, pli, dist)`. * `aci`: the sprite number of the actor invoking `func` * `pli`: the index of the player that is nearest to this actor * `dist`: the 3D Manhattan distance - footnote:[The Manhattan distance between points _p_~1~=(x~1~, y~1~, z~1~) and - _p_~2~=(x~2~, y~2~, z~2~) is defined as abs(x~2~ -- x~1~) + abs(y~2~ -- y~1~) - + abs(z~2~ -- z~1~).] + footnoteref:[mhdist_def,The Manhattan distance between points + _p_~1~=(x~1~, y~1~, z~1~) and _p_~2~=(x~2~, y~2~, z~2~) is + defined as abs(x~2~ -- x~1~) + abs(y~2~ -- y~1~) + abs(z~2~ -- z~1~).] between actor `aci` and player `pli` +// NOTE: , is the comma; the footnote would be truncated at it otherwise. +// For a related issue, see +// http://www.methods.co.nz/asciidoc/faq.html#_why_am_i_having_trouble_getting_nested_macros_to_work + Additionally, `gameactor` accepts optional input arguments. They can be specifyed positionally by following `tilenum`, or be given as values to string keys of the argument table. Each such input argument may be provided in at most @@ -835,10 +863,9 @@ one of these two forms. Furthermore, `func` may be provided as value to the key `'func'` as well. `[2] flags`:: - A number that controls both certain aspects of the `gameactor` call as well as -the run-time behavior of the actor itself. A couple of the latter type are -listed in <>, abbreviated `AF` in the following. +the run-time behavior of the actor itself. A couple of bits for the latter type +are listed in <>, abbreviated `AF` in the following. + These values describe the ``type'' of the actor: `AF.enemy`, `AF.enemystayput` and `AF.rotfixed`. Except for `enemystayput`, they name single bits @@ -926,4 +953,119 @@ out e.g. trigonometrical calculations, there is a need for convenient interoperability between the two ``worlds''. Another purpose of the `xmath` module is to provide _vector_ types that allow -writing concise and clear code involving geometrical calculations. +writing concise and clear code involving geometrical calculations. There are +two types, both containing three components (`x`, `y` and `z`), but differing +in their numeric type. For the most part, `vec3` should be used, whose +components are Lua numbers, i.e. floating point. The other type, `ivec3`, is +part of some game structures, and consequently uses 32-bit integers for its +components. With minor differences, the `vec3` and `ivec3` types share the same +operations and methods. + +[[vector_types]] +The types `xmath.vec3` and `xmath.ivec3` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The constructors of the vector types can be called in several ways. In the +following, they are only described for `vec3`. The conventions for `ivec3` are +completely analogous, but since their creation involves a number type +conversion, the rules about <> +apply. + +`v = xmath.vec3([x [, y [, z]]])`:: +Create a 3-element vector `v` by passing the `x`, `y` and `z` components +separately. Trailing components can be omitted, in which case they are +initialized to 0. + +`v = xmath.vec3(t)`:: +Create a 3-element vector `v` by passing `t`, which can be any variable +indexable with the strings `x`, `y` and `z` (and yielding numbers for these +lookups). For example, `t` can be another (`i`)`vec3`, a `sprite` or even +<> reference, as each of them can be indexed with these three +keys. + +Since the vector types are compound objects, they are always passed around by +reference. For example, consider executing +---------- +v = xmath.vec3(0, 1) +w = v +w.y = 2 +---------- +After this code, the expression `v.x` yields `2` instead of `v`'s initial value +`1`. + +===== Operations for `vec3` and `ivec3` + +In the following, `v` denotes a `vec3` or `ivec3` object reference while `t` +denotes any object indexable with `x`, `y` and `z`. Note that for binary +operations, Lua looks for overridden operators in the left operand first and +the right one next. So, where `t` appears on the left hand side of an +arithmetic expression, it is assumed that `t`'s type does not overload the +corresponding operation or provides the same semantics. Arithmetic operations +always return a (reference to a) new `vec3` object, even if any or both of the +operands have `ivec3` type. + +`v + t`, {nbsp} `t + v`:: +Returns a new `vec3` object whose components are the sum of the respective +components of `v` and `t`. + +`v - t`, {nbsp} `t - v`:: +Returns a new `vec3` object whose components are the difference of the +respective components of `v` and `t` (in the first case) or `t` and `v` (in the +second case). + +`-v`:: +Returns a new `vec3` object with the components of `v` negated. + +`a*v`, {nbsp} `v*a`:: +For a scalar number `a`, returns a new `vec3` object whose components are the +product of those of `v`, and `a`. + +`v/a`:: +For a scalar number `a`, returns a new `vec3` object whose components are those +of `v` divided by `a`. + +`v^zofs`:: +Returns an object of the same type as `v` and with the same components, except +that `v.z` is diminished by `zofs`. Also see the <> for `sprite` objects. + +`tostring(v)`:: +Returns a string representation of `v` for display purposes: ```vec3`'' or +```ivec3`'', followed by the components of `v` in parentheses. + +===== Methods for `vec3` and `ivec3` + +`v:len()`:: +Returns the Euclidean length of `v` in three dimensions. + +`v:lensq()`:: +Returns the squared Euclidean length of `v` in three dimensions. + +`v:len2()`:: +Returns the Euclidean length of `v`, taking only the `x` and `y` components +into account. + +`v:len2sq()`:: +Returns the squared Euclidean length of `v`, taking only the `x` and `y` +components into account. + +`v:mhlen()`:: +Returns the length of `v` calculated using the Manhattan distance +footnoteref:[mhdist_def] in three dimensions between the origin and the +endpoint. + +`v:toivec3()`:: +Returns a new `ivec3` object with the same components as `v`, but converted +<>. + +`v:touniform()`:: +Returns a new vector of the same type as `v` which has the same `x` and `y` +components as `v`, but the `z` element divided by 16 (if `v` is a `vec3`) or +arithmetically right-shifted by 4 (if `v` is an +`ivec3`).footnote:[Right-shifting by 4 can be seen as a division by 16, but +with rounding towards negative infinity.] Also see the description of the +ceiling/floor <>. + +`v:tobuild()`:: +Returns a new vector of the same type as `v` which has the same `x` and `y` +components as `v`, but the `z` element multiplied with 16. diff --git a/polymer/eduke32/source/lunatic/test/rotfixed_actor.con b/polymer/eduke32/source/lunatic/test/rotfixed_actor.con index c3ca5fc4c..fd40b1fdf 100644 --- a/polymer/eduke32/source/lunatic/test/rotfixed_actor.con +++ b/polymer/eduke32/source/lunatic/test/rotfixed_actor.con @@ -34,3 +34,11 @@ onevent EVENT_JUMP money 5 paper 3 endevent + +// Speed up sector effects a little 8-) +gamevar ra_temp 0 0 +eventloadactor GPSPEED + getactor[THISACTOR].lotag ra_temp + mulvar ra_temp 4 + setactor[THISACTOR].lotag ra_temp +enda