Changes between Initial Version and Version 1 of Random_Map_Scripting_Interface

Timestamp:

Feb 23, 2008, 4:18:58 AM (16 years ago)

Author:

trac

Comment:

--

Random_Map_Scripting_Interface

@@ +1 @@
+The RMSI details the functionality of Random Map Scripting which will be used to allow scripters to create the environment that players will need to play in.
+[[BR]][[BR]]
+== TODO ==
+Add the Trigger Reference[[BR]]
+
+== Generic ==
+==== randInt(min, max) ====
+This function returns a random number between min and max.
+==== randFloat(min, max) ====
+This function returns a random decimal between min and max.
+==== chooseRand(multi) ====
+This function returns one of the variable multiple parameters.
+==== abs(x), acos(x), asin(x), atan(x), atan2(y, x), ceil(x), cos(x), exp(x), floor(x), log(x), max(a, b), min(a, b), pow(x, y), round(x), sin(x), sqrt(x), tan(x) ====
+Mathematic wrappers to the Math object.
+==== isArray(var) ====
+This function returns whether the variable is an array or not.
+[[BR]][[BR]]
+
+== Preinitialized Features ==
+Session and Triggers are pre-initialized objects to handle session data and condition/effects respectively. Scripters access their functionality using the with() construct as shown below:
+
+{{{
+ with(Session) {
+ }
+ with(Triggers) {
+ }
+}}}
+
+This keeps the code clean since it forces newbies to keep it in one area, and makes sense to them as they read the code.
+[[BR]][[BR]]
+
+== Players ==
+The Player feature simply returns a player specifier(s). It can be used by triggers, objects, and other appropriate features to specify what player(s) they pertain to. They currently also hold player placement data for use by the !PlayerPlacement object.
+[[BR]][[BR]]
+==== Player(int) ====
+This is the constructor. It sets the player you want it to associate with.
+==== getPlacement() ====
+This method returns an x,y array specifying the player's placement.
+[[BR]][[BR]]
+==== !PlayerTeam(int) ====
+This is the constructor. It sets the team you want it to associate with.
+==== getPlacementArray() ====
+This method returns a multi-dimensional array specifying the placement of each player in team.
+==== getPlayerCount() ====
+This method returns the number of players in team.
+==== getPlayers() ====
+This method returns an array of Player objects.
+[[BR]][[BR]]
+==== !PlayerAll() ====
+This is the constructor. It currently does nothing because you want to associate with all players.
+==== getPlacementArray() ====
+This method returns a multi-dimensional array specifying the placement of each player in game.
+==== getPlayerCount() ====
+This method returns the number of players in game.
+==== getTeamCount() ====
+This method returns the number of teams in game.
+==== getPlayers() ====
+This method returns an array of Player objects.
+==== getTeams() ====
+This method returns an array of !PlayerTeam objects.
+[[BR]][[BR]]
+
+== Sessions ==
+The Session feature returns and defines session data specified by the host usually the player himself when in SP mode.
+[[BR]][[BR]]
+==== Session() ====
+This is the constructor. It currently does nothing except initialize the object.
+==== hasSeasons() ====
+This method returns whether the map should have seasons.
+==== hasTeams() ====
+This method returns whether the players will team together.
+==== hasTeamsLocked() ====
+This method returns whether the players are permanently teamed.
+==== getMap() ====
+This method returns the predefined area that specifies the map itself.
+==== getType() ====
+This method returns the game type.
+==== getAllPlayers() ====
+This method returns the !PlayerAll object.
+==== getSettlementCount() ====
+This method returns the requested number of settlements per player
+==== getSize() ====
+This method returns the requested map size.
+==== getDifficulty() ====
+This method returns the requested AI difficulty.
+==== getSpeed() ====
+This method returns the requested game speed.
+==== getBorderTimer() ====
+This method returns the requested border timer.
+==== getMaxCenters() ====
+This method returns the requested maximum amount of military centers.
+==== getPopCap() ====
+This method returns the requested population capacity.
+==== getStartingResources() ====
+This method returns the requested amount of resources to start with.
+==== getStartingSeason() ====
+This method returns the requested season to start with.
+==== getStartingPhase() ====
+This method returns the requested phase to start in.
+==== getVisibility() ====
+This method returns the requested visibility.
+==== setUserDefined() ====
+This method grabs all the session data and sets them. (used if the scripter doesn't want to ignore user session data)
+==== setType(type) ====
+This method sets the game type for map.
+==== setSettlementCount(int) ====
+This method sets the number of settlements per player.
+==== setSize(int) ====
+This method sets the size of map.
+==== setDifficulty(string) ====
+This method sets the difficulty of AI.
+==== setSpeed(int) ====
+This method sets the game's speed.
+==== setBorderTimer(int) ====
+This method sets the length in seconds Territory borders are activated.
+==== setMaxCenters(int) ====
+This method sets the maximum amount of military centers.
+==== setPopCap(int) ====
+This method sets the population capacity.
+==== setStartingResources(string) ====
+This method sets the amount of starting resources.
+==== setStartingSeason(string) ====
+This method sets the season the game starts in.
+==== setStartingPhase(string) ====
+This method sets the phase every player starts in.
+==== setVisibility(string) ====
+This method sets the visibility of the map.
+==== loadAI(ai) ====
+This method loads a specific ai script.
+[[BR]][[BR]]
+
+== Areas ==
+The Area feature is the parent of most basic functionality that would be inherited by the other more specific objects such as Water, Connection, and Constraint. If it's something that all objects share, it would be put in the Area object. In fact, The map itself is a predefined area whose size is set from 0 to 1 (the center being 0.5).
+[[BR]][[BR]]
+==== Area(parentArea ====
+null)====
+This is the constructor. It recieves the parent area because each area is required to be within another area. If no parent area is given, the area is created anywhere within the map itself rather than another area.
+==== getSize() ====
+This method returns the size of the area.
+==== getLoc() ====
+This method returns the location of the area in an array: array(x,y).
+==== getCenter() ====
+This method returns the center of the area in an array: array(x,y).
+==== getRandom() ====
+This method returns a random location within the area in an array: array(x,y).
+==== getBorder(num ====
+1, distance = null)====
+This method returns an array of random locations within the area border. If distance isn't set, it returns equidistant locations.
+==== setSize(min, max) ====
+This method sets the size of the area. The size is restricted between 0 to 1.
+==== setLoc(x, y) ====
+This method defines where the area will be placed. X and Y is restricted between 0 to 1.
+==== setCluster(min, max) ====
+This method sets the number of area patches (Blob in AOM) to create.
+==== setClusterDist(min, max) ====
+This method sets the allowed distance the patches can be from eachother. Distance is restricted between 0 to 1.
+==== setRadius(int) ====
+This method sets the radius of an area to create a circle.
+==== newVertex(x, y) ====
+This method defines coordinates for a vertex to create a polygon.
+==== rotate(int) ====
+This method is used to rotate the area by a certain amount of degrees (1-359).
+==== create(int=1) ====
+This method registers the area(s) after everything has been configured. If int is specified, it creates int number of copies of the area.
+[[BR]][[BR]]
+
+== Area Groups ==
+The !AreaGroup feature is simply a wrapper for an area array. They can be used to implement the same surfaces on the same areas, connect them using !AreaConnection, and whereever else you would otherwise define one area in.
+[[BR]][[BR]]
+==== !AreaGroup(multi) ====
+This is the constructor. It recieves a variable amount of parameters containing each area you want to group.
+==== addArea(area) ====
+This method adds a new area to the array to allow for individual additions.
+[[BR]][[BR]]
+
+== Surfaces ==
+The Surface feature is simple. It applies, modifies, and removes terrain from a specified area. It also sets the elevation of land from the parent area, or the depth of water. It can be implemented on any predefined area.
+[[BR]][[BR]]
+==== Surface(area) ====
+This is the constructor. It recieves the area the terrain references.
+==== setTerrain(terrain) ====
+This method defines the main terrain to apply or change within the area.
+==== addTerrainLayer(terrain, percent) ====
+This method adds a new terrain layer which borders the area. For example, going from shallow to deep water.
+==== addElevationAlignment(blendFloat) ====
+This method defines a smooth alignment from one elevation to the next within the areas it overlaps. The highest point must gradually blend with the lowest point by defining distance in percentage.
+==== replaceTerrain(old, new) ====
+This method is used when you want a certain terrain type to be replaced with another in the case of overlapping areas.
+==== setForestType(type, percent) ====
+This method is used to set a forest type and a percentage of how much of the land it takes up.
+==== setElevation(min, max) ====
+This method defines the variable height of the area.
+==== setDepth(min, max) ====
+This method defines the variable depth of the water area.
+==== modifyElevation(int, blendRadius) ====
+This method raises/lowers the elevation of each tile by the specified int.
+==== modifyDepth(int, blendRadius) ====
+This method raises/lowers the depth of each tile by the specified int.
+==== clearDepth() ====
+This method clears depth of area.
+==== clearElevation() ====
+This method clears elevation of area.
+[[BR]][[BR]]
+
+== Constraints ==
+The Constraint feature is used to define restrictions. It applies strict rules to make the map work in a specific way.
+[[BR]][[BR]]
+==== Constraint(area) ====
+This is the constructor. It defines the area the constraint(s) will pertain to using an area.
+==== preventOverlap() ====
+This method prevents an area from overlapping the defined area.
+==== preventExit() ====
+This method forces an object or area to remain within the defined area.
+==== preventWalk() ====
+This method prevents units from entering the area.
+==== preventBuild() ====
+This method prevents players from building on the area.
+==== avoidTerrain(terrain, min, max) ====
+This method defines the minimum and maximum distance the defined area can be from a specified terrain.
+==== avoidAreas(min, max) ====
+This method defines the minimum and maximum distance the defined area can be from other defined areas.
+==== avoidArea(area, min, max) ====
+This method defines the minimum and maximum distance the defined area can be from a specific area or areagroup
+==== avoidPassable(min, max) ====
+This method defines the minimum and maximum distance the defined area can be from a passable area.
+==== avoidImpassable(min, max) ====
+This method defines the minimum and maximum distance the defined area can be from an impassable area.
+==== addObject(object) ====
+This method defines the object(s) that must adhere to the constraints.
+[[BR]][[BR]]
+
+== Connections ==
+Connections are special areas used to "connect" 2 or more areas.
+[[BR]][[BR]]
+==== !PlayerConnection(players), !AreaConnection(areas) ====
+These constructors define the type of connection. !PlayerConnection connects players by placement while !AreaConnection connects individual areas within an !AreaGroup or array.
+==== setPercentage(float) ====
+This method is used to cut down on how many connections are generated. So, if there are 10 possible connections and you use this method with the number .5 then only 5 connections will be generated randomly.
+[[BR]][[BR]]
+
+== Water ==
+The Water feature is used to create water. The surface object defines the water's depth. If terrain is set, it's used as the bottom level of the water which can be used to create some cool effects. Maybe we can add some more methods like making stronger waves and other graphical goodies like that if the engine will support it.
+
+==== Water(parentArea) ====
+This is the constructor. it simply defines its parent area.
+==== setType() ====
+This method defines the type of water to use.
+[[BR]][[BR]]
+
+== Territories ==
+The Territory feature is a self-defined area that's generated to divide the parent area equally by the amount specified by the scripter. The parent area can be any defined area (Area, Connection, or Water). Each territory is given an ID according to position. IDs are generated clockwise starting from the territory positioned to the topleft of the area.
+[[BR]][[BR]]
+==== Territory(parentArea) ====
+This is the constructor. It defines the parent area.
+==== divide(int) ====
+This method equally divides the territory a specified number of times.
+==== getNext() ====
+This method equally divides the territory a specified number of times.
+==== rewind() ====
+This method resets and goes back to the first dividend.
+[[BR]][[BR]]
+Here's how the territories would be implemented as documented:
+{{{
+ mapTerr = new Territory(MAP);
+ mapTerr.divide(PlayerAll.getPlayerCount());
+ mapTerr.create;
+ 
+ mapProv = new Territory(mapTerr);
+ mapProv.divide(4);
+ mapProv.create;
+ 
+ function attrition() {
+     // triggers are too sketchy to complete example currently
+ }
+ 
+ trigAttrition = new Trigger(attrition());
+ trigAttrition.enable;
+}}}
+[[BR]]
+
+== Objects ==
+The Object feature places objects of any kind on the map. It works similar to areas and can be applied constraints just like areas. An object type can be a specific object, a unit type (archer/infantry/cavalry), or an array of either for specialized conditions.
+[[BR]][[BR]]
+==== Object(player) ====
+This is the constructor. It uses the Player feature to tell who owns the object.
+==== isOverlap(bool) ====
+This method defines whether the object(s) are capable of overlapping.
+==== setType(object) ====
+This method sets the object type.
+==== setArea(area) ====
+This optional method allows you to place them within a specific area.
+==== setAmount(min, max) ====
+This method defines a minimum and maximum amount of objects you want created.
+==== setDistance(min, max) ====
+This method defines the minimum and maximum distance between each object defined.
+==== setLoc(x, y) ====
+This optional method defines the general location of the object(s).
+==== setLocArray(array) ====
+This optional method is used if more than one player was defined in the constructor and you'd like to give each a certain location.
+==== create() ====
+This method registers the object(s) after everything has been configured.
+[[BR]][[BR]]
+== Object Groups ==
+The !ObjectGroup feature is simply a wrapper for an object array. They can be used to implement the same constraints when placing several objects.
+[[BR]][[BR]]
+==== !ObjectGroup(multi) ====
+This is the constructor. It recieves a variable amount of parameters containing each area you want to group.
+==== addObject(object) ====
+This method adds a new object to the array to allow for individual additions.
+==== create(int=1) ====
+This method registers the objects after everything has been configured. If int is specified, it creates int number of copies of the objects.
+[[BR]][[BR]]
+== Triggers ==
+A trigger is an indefinate iteration that can be stopped and restarted. Triggers are "described" in regular functions. They are necessary to allow for dynamic actions and reactions using conditions and effects. But you don't even need triggers and functions to take advantage of conditions and effects. Conditions and effects are regular functions that can be used globally within the script, and if you need to run it once at startup with no iteration, you are free to do so.
+[[BR]][[BR]]
+==== Trigger(func) ====
+This is the constructor. It defines the function that will be called iteratively and registers it.
+==== priority(int=1) ====
+This method defines the priority the trigger has.
+==== enable() ====
+This method activates the trigger.
+==== disable() ====
+This method deactivates the trigger.
+[[BR]][[BR]]
+Every trigger starts with a preceding function that contains the code we want "triggered". To make it a trigger, you would create a new Trigger object specifying the function you want to work with:
+{{{
+ function trigName() {
+     if(accumulated("food") >= 500) {
+         sendchat("this player has 500+ food!");
+     }
+ }
+ 
+ trigger = new Trigger(trigName());
+}}}
+Now, The trigger is registered and recognized by the engine. You, then, have to activate it to make it work. To activate/deactivate triggers, you use the enable and disable methods. For optimization, you can also set a priority for triggers within 4 different levels (1 being default). Priority must be called before enabling it.
+[[BR]][[BR]]
+
+== Trigger Groups ==
+The !TriggerGroup object is simply a wrapper for a trigger array. They can be used to implement the same.
+[[BR]][[BR]]
+==== !TriggerGroup(multi) ====
+This is the constructor. It recieves a variable amount of parameters containing each trigger you want to group.
+==== addTrigger(trig) ====
+This method adds a new trigger to the array to allow for individual additions.
+[[BR]][[BR]]
+
+== [wiki:Trigger_Reference Trigger Reference] ==
+The Trigger Reference lists the comprehensive condition and effect libraries that are included in the RMSI for dynamic execution.
+[[BR]][[BR]]
+== [wiki:Biome_Reference Biome Reference] ==
+The Biome Reference lists the many Biome features and their functions which standardizes the environment using compatible limitations.