Changeset 1181

Timestamp:

08/10/22 13:51:32 (21 months ago)

Author:

sz

Message:

updated for the current Framsticks version 5.0rc23
(WorldMap?.getAstString() and WorldMap? documentation)

File:

• java/Framclipse/com.framsticks.framclipse/res/framscript.xml (modified) (2 diffs)

java/Framclipse/com.framsticks.framclipse/res/framscript.xml

@@ -6793 +6793 @@
         </type>
         <type name="WorldMap" context="Global context">
-<description><![CDATA[Environment details for "Blocks" and "Heightfield" world type. The most important concept is a "Map", which is the array of Map elements. Internally, Maps have more elements than could be deduced from the user-supplied World.wrldsiz, as additional rows of element are added to provide smooth transitions to the flat surroundings.
-
-Blocks: x/ysize=World.wrldsiz+4 rows of blocks (from which only 2+World.wrldsiz rows are placed within the world boundaries)
-
-Smooth: x/ysize=World.wrldsiz+2 rows of vertices (creating World.wrldsiz+1 rows of triangles, everything within the world boundaries)
-]]></description>
+<description><![CDATA[Environment details for "Blocks" and "Heightfield" world type. The most important concept is a "Map", which is the array of Map elements.]]></description>
                 <element name="xsize" type="integer" flags="1"/>
                 <element name="ysize" type="integer" flags="1"/>
+                <element name="getAsString" function="true" type="string" flags="32">
+                        <description><![CDATA[This function returns the universal polygonal description of the world surface (regardless of the world type). The data is provided in the following simple textual format with each line describing one vertex (3 floating point values) or one face (3 or 4 vertex indices - faces can be triangles or quads), which is a subset of the Wavefront .obj file format:
+
+v first vertex coordinates
+v second vertex coordinates
+v ...etc
+f first face indices
+f second face indices
+f ...etc
+
+For example, the default flat world consists of 4 vertices and 1 quad face:
+
+v 0 0 0
+v 20.0 0 0
+v 20.0 20.0 0
+v 0 20.0 0
+f 1 2 3 4
+
+Internaly, the data returned by this function is generated by the 'scripts/worldmap-faces.script' file, so you can refer to its source if needed.
+The first argument to getAsString() (if not null or empty string) selects an alternate userscript to be used instead of the default "worldmap-faces.script", allowing for extension and customization.
+Examples:
+WorldMap.getAsString(null,null) //use the default script
+WorldMap.getAsString("myscript","myarg") //calls "WorldMap_myscript", passing "myarg" to its main_args() function.]]></description>
+                        <arguments>
+                                <argument name="alternate script" type="string"/>
+                                <argument name="special arguments" type="untyped"/>
+                        </arguments>
+                </element>
                 <element name="getHeight" function="true" type="float">
                         <description><![CDATA[Height at any 2d coordinate]]></description>
@@ -6809 +6832 @@
                 </element>
                 <element name="getMap" function="true" type="Object">
-                        <description><![CDATA[retrieve map cell object]]></description>
+                        <description><![CDATA[Retrieve the map element object for a given grid coordinates (x,y), where 0<=x<xsize, 0<=y<ysize.
+
+The obtained value type depends on the current world type.
+- Blocks world objects provide 'z' and 'type' values (z is the block height, type is 0=flat block, 1=west-east slope, 2=north-south slope).
+- Heightfield world objects provide just the 'z' value (which is the grid point height).
+
+See the 'scripts/worldmap_faces.script' file for a practical example on how to obtain the world geometry data using WorldMap.getMap().
+
+Quirks: Internally, maps have more elements than could be deduced from the user-supplied World.wrldmap, as additional rows of elements are added to provide smooth transitions to flat surroundings, which is reflected in 'xsize' and 'ysize'.
+WorldMap.getMap() arguments refer to this internal representation, so the object corresponding to the first map element is not (0,0), but (1,1) for Heightfield or (2,2) for Blocks world. Not starting from (0,0) can be convenient - for example, given any valid grid coordinates (x,y), all its neighbors are also valid and can be requested through getMap() without introducing any special cases in the code.]]></description>
                         <arguments>
                                 <argument name="x" type="integer"/>