Concept Lua API 2 (Draft 0.6) ================= C1 - Object Based Syntax (coded - besides lines starting with a ".") ------------------------ The new API provides successor functions for all basic functions of the old API with simplified names and arguments. (As the naming of the successor functions is not yet fixed just a few examples are listed. This set of functions will be completed to ensure that all previous styles of level programming are supported in the API as well). The following example based description explains the idea of the new object based syntax additions: Namespace "en" Any system object or function is addressable as "sysname" and "en.sysname" Special value types: position - a position within the world that can be described by an x and y coordinate object - an Enimga object like a stone, item, floor, rubberband,... world - a singleton type for the world that contains all objects namedobjects - a singleton type for the repository of all named objects group - a list of objects tile - a description of objects at a common grid position (floor, item, stone, actor) tiles - a singleton type for the repository of all tile instances Special objects given at init: wo world with map and global attributes of type no named object repository of type ti tile template repository of type Let "obj" be an example object reference of a stone/item/floor (type ). Grid Positions are table/objects: pos = po(7, 3) -- a function "po()" pos = po({7, 3}) pos = obj -- every object is a valid position pos = po(12.3, 3.7) -- position within a grid (for an actor) Position constants {7,3} -- a valid position for all arguments and operations (see caveats) Access to x, y coordinates: x, y = pos.x, pos.y x, y = pos["x"], pos["y"] x, y = pos:xy() x, y = obj.x, obj.y x, y = obj:xy() Position calculation pos = obj + {2,7} dpos = obj1 - obj2 dpos2 = 2 * dpos Center positions for set actors pos_centered1 = pos + {0.5, 0.5} pos_centered2 = #pos pos_centered3 = #obj Round a position to a grid grid_pos = pos:grid() Position comparison pos_centered1 == pos_centered2 Setting a single attribute of objects including global attributes of world: obj["attr_name"] = value wo["Brittleness"] = 7 Setting multiple attributes at once: obj:set({attr_name1=value1, attr_name2=value2}) Requesting attributes of objects including global attributes of world: value = obj["attr_name"] value = wo["Brittleness"] if wo["IsDifficult"] then ... end Reset an attribute to its default - "delete": obj["attr_name"] = nil Creating a new object: wo[pos] = {"st_chess", color = 0, name="Atrax"} -- on edge of grid pos wo[#pos] = {"ac_bug"} -- actor centered on grid pos wo[pos] = {"#ac_bug"} -- actor centered on grid pos wo[pos] = {"ac_bug", 0.3, 0.7} -- actor with offsets to pos wo[my_floor] = {"it_wand"} -- set an wand on top of a given foor Naming an object: no["Atrax"] = obj Consecutive naming of objects (building object groups) wo[pos] = {"st_chess", color = 0, name="Atrax#"} For each call of the line above the new object will be named with a unique number appended after the "#" giving "Atrax#1", "Atrax#2", "Atrax#3", ... Requesting an object: obj = it(pos) obj = it(x, y) obj = st(pos) obj = wo:it(pos) my_item = it(my_floor) -- get the item that is on top of the given floor obj = no["Atrax"] Killing an object: obj:kill() wo[pos] = {"it_nil"} Comparing objects obj1 == obj2 Existance of an object obj:exists() -obj -- unary minus operator on object if -obj then ... Messages: my_boulder:message("direction", WEST) my_boulder:direction(EAST) my_door:open() Classification of objects: obj:is("st_chess") obj:is("st") obj:is("st_chess_black") Group of objects: group = no["Atrax#*"] -- a group of all matching objects -- wildcards "*","?" allowed group = grp(obj1, obj2, obj3) group = grp({obj1, obj2, obj3}) -- a group of objects set up in a table Many operations can be applied to groups floor_group[friction] = 3.2 -- set attribute on all floors in the group door_group:message("open") door_group:open() stone_group:kill() wo[floor_group] = {"it-coin2"} -- add some money on all floor positions wo[pos] = {"st_switch", target=door_group, action="open"} wo[pos] = {"st_switch", target="door#*", action="close"} Group operations doors_lasers = doorgrp + lasergrp -- join of two groups lasergrp = doors_lasers - doorgrp -- difference of two groups common_doors = doorgrp1 * doorgrp2 -- intersection of two groups For loops over a group for i = 1, #mygroup do obj = mygroup[i] ... end for obj in mygroup do ... end Setting and connecting two vortices: wo[{3,4}] = {"it_vortex", name="vortex1", destination="vortex3"} wo[{8,6}] = {"it_vortex", name="vortex2", destination="vortex1"} wo[{8,6}] = {"it_vortex", name="vortex3", destination={"vortex1","vortex2"}} Tiles: ti[" "] = {"fl_sand"} ti[" w"] = ti[" "] .. {"it_wand"} ti[" "] = {"fl_abyss"} -- redefinition causes error to avoid common -- mistakes wo[{3,4}] = ti[" w"] wo[{5,6}] = ti[" "] .. {"st_chess"} width, height = wo(ti, " ", { -- second arg: default tile key that "########", -- defines the base, too - this example "## w##", -- is 2 chars per tile/grid "########" }) Note: Tiles kann be used after the initialization as well: function my_callback(value, sender) wo[sender] = ti[" w"] end C2 - Object reference validity and usability (done) -------------------------------------------- Objects existance and validity can be checked at via the "obj:exists()" method or the operator "-obj". Not existing objects are still of type object (not nil like in old API!). These "null" objects are not equal concerning the Lua "==" comparison to any object, even themself. Write access, kill of and messages to "null" objects are silently ignored. World set objects to "null" object position is ignored, too. This allows loops and group usage even with "null" targets without problems. All read operations that return object specific values which are not usable for group operations and can just be used with a single object as target will throw an error if this object is a "null" object. The application will no longer crash. Just a backtrace will be shown like on other level exceptions. C3 - Booleans and Nil (mainly done) --------------------- All boolean type attributes and values in the new API are Lua 5.0++ booleans with values "true" and "false". The engine internal value representation takes boolean as another explicit type. Type mismatches on transfer of boolean values from or to Lua will no longer occur. Some attributes and values of the old API that did take values 0 and 1 may change to other types than boolean due to other API concepts. Setting an attribute value to "nil" causes the value to be deleted. Any further access returns the default value for the attribute. C4 - Multitarget and Multiaction (coded) -------------------------------- The target-action paradigm is extended to a multitarget and multiaction messaging system that is even configurable on the senders state. Every object can take objects, groups of objects or namestrings (including wildcards) as target: {"st_switch", target=my_laser, action="on_off"} {"st_switch", target=no["my_doors#*"], action="open_close"} {"st_switch", target="my_doors#*", action="open_close"} Note the subtle difference between the last two expressions: The first one evaluates the wildcarded string immediatley and builds a fixed group of the current objects that fit the name pattern. The second string is stored as given and will be evaluated at the moment the action is performed. This is what you need in tile definitions, as the desired target do not exist at the moment of the tile definition. Multiple targets can be declared and each target can take a different action: {"st_switch", target={my_laser, "my_door#*", "my_function"}, action={"on_off", "open_close", "callback"}} The default action for all functions is "callback", which can thus be omitted: {"st_switch", target="my_function"} The default action for all objects is "toggle", which can thus be omitted: {"st_switch", target="my_laser"} Every callback takes the arguments (state_value, sender) where "state_value" is an integer value that represents the internal state of the sender object. For switch like objects the state will be 0 for "off" and 1 for "on". Other objects like fourswitch etc. will count the their states from 0, 1, 2,... For special cases, especially for editor based levels, the author can specify different target/action behaviour based on the value of the sender objects state. For each state the following special targets and actions preceed the default target and actions given above: {"st_switch", target_0="my_door", action_0="close", target_1="my_laser", action_1="off"} The multitarget feature is the successor of the old signal feature. In contrast to signals that were bound to tile positions like "stone on grid {15, 4}" the multitarget addresses objects themselves. The action will find its target even when the user swaps it to another grid postion. C5 - Renaming (partially done) ------------- The necessary API changes gives the unique opportunity to simplify many old names and to make them consistence. None of names used above is fixed. It is up to the level authors to agree on a naming scheme. Note that valid Lua names start with letter or underscore and consist just of these plus numbers. Just the following rules and conditions need to be observed: - Short 2 or 3 letter names for the namespace and the special objects - System attribute and message names have to be valid Lua names not starting with underscore - User attributes start with an underscore - System attribute and method names are disjoint - Identical system attributes or methods have identical behaviour for all objects - User names for objects do not start with "$","#" or "%", do not contain a character out of ",;" and do not end with "#" - Object Classnames should use a common scheme of underscore/hyphen usage: Either underscore only, or first hyphen and all other underscore,... (st_chess_black, st-chess_black, ...) Decision of Draft 0.60: all object names will uses exclusivly underscore! C6 - Global Variables (coded) --------------------- Global variables are handled as attributes of the special world object "wo". Write access on variables will be checked and can cause actions if necessary. A write to a read only variable like "IsDifficult" will be silently ignored. C7 - Critical functions ----------------------- All critical functions will be abolished to ensure that new levels will be suited for upcoming features. For the very few existing levels of the distribution that depend on such features exceptions will be hardcoded that will keep these levels to conflict with the new features. C8 - Oxyd (coded) --------- The color attribute is an integer value (0, 1, ..., 7). Oxyds can be set like any other stones. If no color attribute is specified pairs of oxyds with the same color will be set. To guarantee fair distributions and levels that are solvable the author can declare minimum and maximum conditions and groups of oxyds like: wo:shuffleOxyd({grp1, max=0}, {grp1, grp2, min=2}, {grp1, grp3, min=1, max=1}) As a shortcut groups of oxyds can be declared to be positioned either circular or linear. This declaration expands to all rules necessary to avoid any neighbour oxyd pairs. wo:shuffleOxyd({grp(ox1, ox2, ox3, ox4, ox5, ox6), circular=true}, {grp2, linear=true}) C9 - Rubberband --------------- Rubberband is an object that can be referenced and checked for existance. C10 - Name inheritance (partially done) ---------------------- Items like it_seed, it_rubberband that change into stone or rubberband objects on activation will inherit their name to the successor stone object. C11 - Checkerboard Floor (coded) ------------------------ Every floor takes an attribute "checkerboard". If set to an integer value 0 the floor will only be placed on grids with x+y being even, if set to 1 the floor will be placed only on grids with x+y being uneven. ti["x"] = ti({"fl_rough_red", checkerboard=0}) + {"fl_rough_blue", checkerboard=1} generates an arbitrary shaped checkboardfloor on areas with tile "x" on the world map. C12 - Puzzle ------------ Puzzles can be autoconfigured and shuffled by the engine. Besides the single puzzle stones a dummy stone named "st_puzzle_auto" can be set. All adjacent "st_puzzle_auto" and "st_puzzle_hollow" of the same color will be configured to a puzzle with maximum number of connections: ti["#"] = {"st_puzzle_auto"} ti["*"] = {"st_puzzle_hollow"} wo{ti," ",{ " # ", "##*#", "### ", " # "} results in a puzzle: | /T+- \+/ | with the upper "+" being a hollow cross. If any of the involved puzzle stones has an attribute "shuffle" set to "true" the complete puzzle will shuffled. If the value of any puzzle stone is an integer it will be taken as the number of permutations to be applied. The maximum number of all values will be taken. Shuffle occurs by permutation of rows and columns that a marble can reverse. By default it is assumed that the user can permute rows and columns on every side which is not blocked by a stone that is not hollow. In case the puzzle is only accessable from one side the author can add attributes "permute_v" and "permute_h" with boolean values to every puzzle stone that does not follow the standard rule. As hollow puzzle stones will never be permuted to the border of a puzzle the author can ensure that every shuffle results in a solvable puzzle. Appendix ======== Index/member interpretation and operations of new types: -------------------------------------------------------- value = number|string|boolean|object|nil add |group|position ? Enigmaobject: x, y - grid position access exists() is() - (string) - test kind kind() - () - get most specific kind kill() - () - kill object message() - (string [, value]) - send message with an optional value set() - (table) - set multiple attributes given in a table as key, value pairs xy() attribute name - set/get attribute other String not prefixed by "_" - message valid Operations: + - (object|position|table) + (object|position|table) - - (object|position|table) - (object|position|table) # - #object -- center - (unary) - -object -- existance == - object == object Position: x, y, - grid position access grid() - returns a position aligned to the grid xy() - returns x, y valid Operations: + - (object|position|table) + (object|position|table) - - (object|position|table) - (object|position|table) * - (number|position) * (number|position) / - position / number # - # position == - position == position . .. - position .. position Namedobject: $String - reserved for future usage String - named object access - returns nil if not existing - name must not include wildcard chars *,? String*? - get named group with wildcards *,? Worldobject: [object|position|table|group] = table|tile - write access to world grid [string] - global world attribute read/write access () - (ti|function, string, table) -- initialization "wo(,,)" fl() - (position|table|obj|(num,num)) - get floor at position it() - (position|table|obj|(num,num)) - get item at position st() - (position|table|obj|(num,num)) - get stone at position init() - (ti|function, string, table) -- method synonym for () Group: 1, 2, 3,... - positve integer as sequence index like table read access String - on write: set attrib on members - on access: call method or send message on object valid Operations: + - join of groups * - intersection of groups - - difference of groups # - length, inherited from table Tile: valid Operations: .. - concat tiles ti(table) - new tile Tiles: String - table like read access with string as index - write only on not yet existing indices - no overwrite assign (table|tile) Global Functions (to be defined) ---------------- po(table|[num,num]|obj) fl(position|table|obj|(num,num)) it(position|table|obj|(num,num)) st(position|table|obj|(num,num)) Lua Caveats: ============ It is a basic LUA feature that the user has no real control about the used variable types. This causes overall trouble: a = "3" b = "7" c = 4 b - a == c -- is true as 7 - 3 == 4 c + a == b -- is false as 4 + 3 == 7 but 7 ~= "7" A similar LUA problem may hit authors in the usage of position constants. Expressions like {7,3} may be used anywhere as position arguments as they are autoconverted into positions. But care must be taken with direct calculations and variable assignments of constant positions: table = {7, 3} -- this variable is a simple table with two numbers at -- the indices 1 and 2 but it is not a position wo[table] = obj -- o.k. as the table gets now converted as an argument pos = #table -- is not a centerd position but a number with value 2 -- as it the length operation of a table pos = table + {1,2} -- error as two tables cannot be added like positions pos = obj + table -- o.k. as obj is a position that forces an autoconvert -- of the table Another similar Lua caveat exists in the position comparison. Even though you can use objects as position standins anywhere else the Lua comparison of variables priorises the type comparison to the value comparison: pos = po(3, 5) wo[pos] = {"st-switch"} obj = st(pos) pos == obj -- false as the types differ pos == po(obj) -- true as types and values are equal Lua index syntax - different treatment of numbers, names and strings: 1, 2 -- are valid Lua numbers x, y, otto2, _myX -- are valid Lua names "$secret", "1", "fl-abyss" -- are just Lua strings x = 7 pos = po(3, 5) pos["x"] -- valid table like access to x coordinate pos[x] -- error as pos[7] is accessed pos.x -- valid member access that is equivalent to pos["x"] obj["state"] -- valid access to attribute "state" obj[state] -- error as global variable "state" is first evaluated (nil) obj.state -- valid access to attribute "state" tab[1] -- valid table access to first entry tab["1"] -- table access to entry at key "1" which is not the first -- table entry but likley nil. tab.1 -- error - Lua needs a valid Lua-name as member