# Random Generation in CoffeeMud 5.9
Introduction to Random Generation Overview of XML Tags Using the Random Generator Glossary of XML Tags Area Room Mob Item Affect Ability Culturalability Behavior Content Exit Race Faction | ## Introduction to Random Generation Random generation in the realm of mud areas, rooms, items, mobs, and so forth is a strange proposition. In the end, it always boils down to selecting among known, fixed, and constant alternatives that make sense in a particular context. For example, a mob that might be named "George" or "A path in the forest" is certainly random, but doesn't make much sense, so we tend to restrict our alternatives in some way. Also, selecting evenly among alternatives, while certainly the most common thing you will do, also sometimes doesn't make sense. A random Moon description might include words like "full", "new", "crescent", "half", and "BLUE". However, just because you want the "BLUE" alternative to be available, doesn't mean you want it to have an equal chance of describing your moon as the other choices. Lastly, sometimes the context in which an alternative makes sense can be extremely narrow. Having "a rat" as a random monster in your dungeon almost always makes sense, except in the "cat room". Again, judgement must come into play. All of these considerations and more have gone into the devising of a random mud engine, and particularly to the format of the input data it uses. This engine receives a series of sets of alternatives which may include a relative weight for each alternative, and potentially the context in which each alternative applies or doesn't apply, and then makes selections and instantiates real mud objects based on those selections. The input to the engine is a very specifically built XML file, and the output is actual mud objects (mobs, items, areas, rooms, or all the above) in your game. ## Overview of XML Tags The random generator works by reading a specially-written XML document that contains tags describing the object or objects to generate. For example, area generation looks for tags named <AREA />, mobs for <MOB />, items for <ITEM />, rooms for <ROOM />, and so forth. The embedding of tags can also be significant. For example, to generate a mob from a given <MOB /> tag, the tag must either contain a NAME attribute, or a <NAME /> tag embedded inside the <MOB /> tag. Another example would be that room tags may contain mob and item tags. Generation sometimes requires that a specific starting object be named by ID, in which case an ID attribute may be found on the tag, allowing it to be referenced globally, no matter where it is embedded. The basic tag types are AREA, ROOM, MOB, ITEM, and STRING. Any tag that contains other tags of the same tag type is a Container tag, and usually has rules in the form of special attributes for how to select among the alternatives in the container. In cases where one of something is called for, but multiple options are available, and no rules are found for how to select among them, a random roll will be made. In cases where one or more of something is allowed, and multiple options are available, all the alternatives found will be selected. Each basic tag type is used to build an object of that type. For instance, the MOB tag is used to build a MOB. Therefore, each basic object type must have other tags or attributes to "fill in the details", such as name, level, and so forth. These Details may be defined as variables on the command line using GENERATE or by the "define" attribute, or may be given as an attribute of the basic tag, or as other tags inside the parent tag. A Detail given as an attribute always supersedes any detail given as internal tags, no matter what. A detail found as an defined variable identifier, supersedes both tags and attributes. See the glossary for more tails on each major tag type. Basic tags may also have special pre-defined variables to help give some context to help with their parsing, and will often cause variables to be defined as their details are filled in. Basic tags also have certain required details which must be resolved for the object to be created, and other optional details which may or may not be given, and which are extremely object-specific. Again, the glossary entry for each basic tag type will have more information about this. Tags are always evaluated recursively, from first to last. Any tag may contain zero or more of the following meta-attributes:
id | exposes the tag to either the Generate command, or to the "insert" or "like" attributes.
load | the xml inside the file named is inserted into the tag
like | a comma separated list of other tag "id"s of the SAME TYPE. These may NOT be container tags. This will allow the current tag to be parsed as if it contained the same tags and attributes as the listed tags. This is useful for making one-off variations on existing tag structures.
insert | a comma separated list of other tag ids. The targeted tags may be of any type, and may be containers. It will cause the tags to be parsed and the resulting tags added as contents of the host tag as if they were already inside it. Remember, the listed tags will be parsed first, so any "condition", "select" or other operations will occur.
copyof | a tag "id" or standard class id. This will cause the stats and attributes and other details of the listed items into the current object.
validate | a boolean expression which must evaluate to true for the tag to be finally built into an object. Check "condition" below for more information....
condition | the value is a boolean expression which must evaluate to true for the tag to be included in its parent. This is similar to "validate" except that "condition" determines whether a tag is among the allowed choices, whereas "validate" determines whether, after being chosen, it is finally built into a final thing (whether string, mob, item, whatever). These expressions may use boolean operators like AND and OR and NOT (or !), string constants are always single-quoted 'string', string comparison operators include = , !=, and IN to check to see if the lhs string is a substring of the rhs string. Numeric comparisons may be made as well, and numeric comparison operators include > < >= <= != =. Parenthesis may be used to group sub-expressions. Defined variables may be included, but only if preceded by a $ character. For instance, to check if the variable "bob" is equal to "bobvalue", you would enter $bob='bobvalue'. Undefined string ids are treated as ''. Remember that in XML, a < and > characters can not appear in attribute values, which is why they must be written as &lt; and &gt; in your xml.
define | this attribute is only used if its "condition" is met, and it is "selected" by its parent tag, if applicable. It is a comma separated list of any combination of the following: "id": either a new or existing identifier, in which case the value that this tag resolves to will be set to that identifier, allowing it to be used in "condition", tag values, or other places. "id=value": will set the new or existing identifier "id" to the given constant "value". "id+=number": see below "id*=number": see below "id-=number": see below "id/=number": Will attempt to evaluate the existing value of the identifier"id" as a number, and perform the given operation upon it with the "number" given. For instance "bob+=3" will add the number 3 to the current value of the identifier "bob". Any undefined "id" will be treated as if it were 0. When dealing with areas, there is an extra feature of defined identifiers. An identifier whose name starts with "_" will persist for every tag and object in the room's "room group". An identifier whose name starts with "__" will persist throughout the entire area. Otherwise, any variables defined using this command will persist only for one room.
predefine | identical to "define", but always evaluated when encountered.
select | used mostly by container tags, this attribute allows you to specify how multiple choices are resolved by this tag. More than one selection may be made, which makes sense when selecting MOB tags for a ROOM. However, sometimes it does not, such as when selecting a NAME for a MOB. In those cases, any remaining multiple-choices are always selected randomly from. Possible values are: "all": always selects every choice. "any-X": selects any X** of the choices, without repeating. Make sure you have another choices to cover the possible value of X! "pick-X": same as "any-X", but the tag choices will be checked for the "pickweight" is container-entry attribute, and is used only when the parent tag is using 'select="pick-X" ' as a relative weight when selecting among the choices. "limit-x": selects up to X** random choices, but less is OK too if no more. "repeat-X": always selects every choice, and treats the choices as if enough of them actually existed to select X** of them, even if not enough choices were given. "none": always selects none of the choices (why would anyone use this?!) "first": selects the first choice (another stupid one) "last": you guessed it, select the last choice "first-X": selects the first X** choices. "last-X": selects the last X** choices. ** Where you see X above, this may be a number, or a math formula or math expression. (see mud help on math formulas/math expressions)
merge | must be "true" if two tags with the same ID are included in the same xml document. It permits some of the tag parameters, and all of the content tags, to be merged together into a single referenced tag. In this circumstance, child tags of parent tags which are being merged may optionally include "merge=false" to prevent duplicates from being formed.
pickweight | a helper attribute for the "select" attribute, when a "pick" value is used by the select attribute. See "select" attribute above.
action | used by string-type choices to inform the engine on how to combine the multiple choices into a single string. Possible values include: "append": append the tags value to the string as built so far. "replace": completely replace any string build so far with this ones value. "prepend": always put this strings value at the beginning of the final string
requires | a comma-separated list of variable identifiers which must have already been defined before this tag can be evaluated. Such variables are usually defined by the user of the GENERATE command, but can also be defined at parse-time by the "define" attribute, if you are creative. Each item in the list is of the format "id=type", so that the parser can check to see not only if the variable is defined, but that it is defined properly. Possible types include "#" for a number, "int" for an integer, "$" for a string, or a semicolon-delimited list of possible string values.
Tag values: A non-container non-basic tag will typically have a string value. This value may contain any embedded variables or identifiers, so long as they are preceded with a $ character. A string beginning with a $ character will be assumed to be an identifier, and will be searched for within the list of defined variables and identifiers. If the identifier resolves to a tag, the tag will be parsed as a string. If the identifier resolves to a string, so much the easier. Defined variables or tag names can also be embedded in {} characters; for example: ${ame}. When embedded in this way, the name may be preceeded by: "u:" to force to all-uppercase "l:" to force all-lowercase "p:" to force plural "c:" to force to be capitalized (first letter upper, rest lower). Special embedded variables: $SYSTEM_RANDOM_NAME:[NUMX]-[NUMY] generate a random name with between NUMX and NUMY syllables. ${STAT:[STATNAME]} embed the value from another stat on the same object. STATs are things like NAME, DISPLAY, DESCRIPTION, etc... ${STAT:[PATH]:[TO]:[ANOTHER]:[OBJECT]:[STATNAME]} embed the value from another objects stat, potentially in a different room. Where path-to-another-object may be: ROOM to refer to the room containing the object, NORTH,SOUTH,EAST,WEST,UP,DOWN,NORTHEAST..etc.. to specify a room in a specific direction, ANYROOM to specify any room connected to this one, MOB to specify any mob in the room, ITEM to specify any item in the room, AREA to specify the area object, or AREAGATE to specify a connecting room outside the area. For example a string such as: "To the east is the residence of ${STAT:ROOM:EAST:MOB:NAME}" would embed the name of a mob in a room to the east of the current room. This command may internally cause post-processing if necessary, and so is almost guaranteed to always work unlike some of the special ROOM_ tags. (a(n)) will remove any indefinite or definite articles from the string immediately following it and replace it (or insert) either "a" or "an" depending on the first letter of the word. ## Using the Random Generator There are currently two ways to use the Random Generator, one is the Archon GENERATE command, and the other is the Area type "StdAutoGenInstance". Generate Command: The most straightforward way to access the random generator is using the Archon GENERATE command. The usage is as follows: GENERATE [OBJ TYPE] [ID] (FROM [FILENAME]) ([VAR]=[VAL]...) ([DIRECTION]) This command uses an xml file to generate random content for your mud. This content can be anything from whole areas, to rooms, mobs, items, or simple strings. By default, the content is built from the file in resources/randareas/example.xml, though the builder may specify his or her own xml file path as one of the many arguments. The arguments, briefly, are:
OBJ TYPE | One of the following: AREA, ROOM, MOB, ITEM, or STRING
ID | one of the "id" xml attributes defined on any tag in the XML file. Use GENERATE STRING LIST for a list of all "id" attributes defined in your file.
FROM "path/to/xmlfile.xml" | An optional argument to specify your own xml file, with the resources directory being the default root.
VAR=VAL | One or more variables and their definitions. Many tags will have a specific set of required variables which must be defined in order for the content to be generated. Failing to specify one of the required variables will cause an error message listing the variables which must be defined, and the type of data required for the variable. Variable types which list numbers as their data types may also have math expressions values (so you can use random numbers). See the help on MATH EXPRESSION for more information on this. In addition to required variables, you may also use the space to enter one or more "override" values. Many object fields (such as LEVEL for mobs and items, or NAME, etc) as well as the XML id tags, can have their "random" values overridden by defining them using the generate command.
DIRECTION | This applies only to ROOM and AREA object types. The object, if successfully generated, will be linked to the current room that the player is standing in, in the direction they specify.
The GENERATE command is an interesting way to deliver large amounts of dynamic content for your world, though it can never replace the caring touch of a real, creative builder. If anyone is interested in writing their own xml content, please open up the /resources/randareas/example.xml file and begin reading it and all of the LOADed files. Use those file as an example on how to construct your own. Examples of the Generate Command: generate area maze_dungeon from randareas/example.xml areasize=50 areaname=test level_range=10?20 aggrochance=50 theme=kobolds south generate string list StdAutoGenInstance Area Type: The StdAutoGenInstance area type is specially formulated to replace any rooms of its own with auto-generated rooms and content. This area type is, firstly, an Instance generator. That means that each group that goes into the area will have their own unique generated rooms to play in, which will be different from any other groups, and will persist until the group gets tired of playing it (causing the area to time-out and be garbage collected). This area type also permits the path and name of the top-level random generation xml file to be specified, where the /resource directory is considered the default path root. Lastly, any required or optional variables. Many tags will have a specific set of required variables which must be defined in order for the content to be generated. Failing to specify one of the required variables will cause the area generation to fail, putting an error message in your mud.log file. Variable types which list numbers as their data types may also have math expressions values (so you can use random numbers). See the help on MATH EXPRESSION for more information on this. In addition to required variables, you may also use the space to enter one or more "override" values for existing defined things. ## Glossary of XML Tags AREA tags: As the highest-level possible tag, an area is parsed only with the variables it is given on the GENERATE command line, and using whatever it can find in its XML contents for its details. All details mentioned below will automatically cause a variable to be defined or re-defined when they are parsed. The variable will be called "AREA_DETAILNAME". For instance "AREA_CLASS" for class, and "AREA_NAME" for name. The layout of an area will cause its rooms to be logically grouped up into streets, "leaf" rooms (rooms with only one exist), and other logical groupings. "leaf" rooms are always done first, followed by streets, and others. The layout will automatically define certain variables for each room to help with parsing the rooms details. These variables include: $AREA_NUMLEAFS: the number of leaf rooms for the whole area $ROOMTAG_NODETYPE: one of surround, leaf, offleaf, street, square, interior $ROOMTAG_NODERUN: for streets, which way they run. Values are ns, ew, nwse, nesw $ROOMTAG_NODEFLAGS: various rooms flags. Values include: corner, gate, intersection, tee, offleaf $ROOMTAG_NODEEXITS: comma separated list of all exits from a room $ROOMTAG_NODEGATEEXIT: if this room is a "gate" rooms, which direction is the gate in. $ROOMLINK_N, $ROOMLINK_S, $ROOMLINK_E, $ROOMLINK_W, etc: "true" if an exit exists that way. $ROOMTITLE_N, $ROOMTITLE_S, $ROOMTITLE_E, $ROOMTITLE_W, etc: if already done, the title of a room that way. $NODETYPE_N, $NODETYPE_S, $NODETYPE_E, $NODETYPE_W, etc: type of room node in that direction, if any. Required details: "CLASS": The CoffeeMud class type to use to create the area. "NAME": The name of the area. Must be unique to your MUD. "LAYOUT": The name of the layout generator to use. At the moment, supported layouts include MAZE, BOXCITY, BOXCITYSQUARE, CROSS, GRIDCITY, TREE, APARTMENT "SIZE": The number of rooms to create in the area. Optional objects: (See below for details on these object tag types and their details) "AFFECT" "BEHAVIOR" "ROOM" Optional details: (See Archon's Guide) "CLIMATE" "DESCRIPTION" "THEME" "BLURBS" "PREJUDICE" "BUDGET" "DEVALRATE", "INVRESETRATE" "IGNOREMASK" "PRICEMASKS" "AUTHOR" "ATMOSPHERE" ROOM tags: Parsed with variables from the generate command, and from any defined variables internal, and from any internal tags and attributes, and from any variables defined by its AREA tag. As with areas, its details will cause variables beginning with ROOM_ to be defined. Required details: "CLASS" "TITLE" "DESCRIPTION" Optional Objects: (See below for details on these object tag types and their details) "MOB" "ITEM" "AFFECT" "BEHAVIOR" "EXIT" You can also specify a "LAYOUT" attribute on a room tag, in which case all rooms contained inside that room tag (or inserted, or whatever) are used to build multiple rooms from that layout, much as specified above on the AREA tag. MOB tags: Parsed with variables from the generate command, and from any defined variables internal, and from any internal tags and attributes, and from any variables defined by other room tags. As with areas, its details will cause variables beginning with MOB_ to be defined. Required details: "CLASS": normally the CoffeeMud class the mob will be made from, though it may also be the word catalog in order to select a mob from your catalog, in which case "name" also becomes a required detail. Optional Objects: "MOB" "ITEM" "AFFECT" "ABILITY" "BEHAVIOR" "FACTION" Optional details: (See Archon's Guide) "RACE" "HPMOD" "LEVEL" "NAME" "DISPLAY" "DESCRIPTION" "MONEY" "ALIGNMENT" "DISPOSITION" "SENSES", "ARMOR" "DAMAGE" "ATTACK" "SPEED" "TATTS" "EXPS" "IMG" "FACTIONS" "VARMONEY" (plus or minus others depending upon class) The "RACE" detail can be the name of a race, or resolve to a RACE tag, see below. ITEM tags: Parsed with variables from the generate command, and from any defined variables internal, and from any internal tags and attributes, and from any variables defined by other room tags. As with areas, its details will cause variables beginning with ITEM_ to be defined. Required details: "CLASS": normally the CoffeeMud class the item will be made from, though it may also be the word catalog in order to select an item from your catalog, in which case "name" also becomes a required detail. This may also start with the string "metacraft:", in which case the remainder of the "class" value becomes either the name of the item to metacraft, the word "anything", "all", or the words "any-" or "all-" followed by the ID of the common skill to use. "metacraft:" class strings may also end with the characters "<" followed by a math expression evaluating to an upper level limit for the item to craft, ">" for a lower limit, or "=" followed by a the base class ID to to filter in. Optional Objects: "MOB" "ITEM" "AFFECT" "CONTENT" "BEHAVIOR" "EXIT" Optional details: (See Archon's Guide) "USES" "LEVEL" "ABILITY" "NAME" "DISPLAY" "DESCRIPTION" "SECRET" "PROPERWORN" "WORNAND", "BASEGOLD" "ISGETTABLE" "ISREADABLE" "ISDROPPABLE" "ISREMOVABLE" "MATERIAL" "DISPOSITION" "WEIGHT" "ARMOR" "DAMAGE" "ATTACK" "READABLETEXT" "IMG" "NOWEAR" (set to true to prevent the item from being automatically worn by mobs) (plus or minus many many others depending upon class) "ShopKeeper" type classes may use "SHOPINVENTORY" tags to hold ITEM, MOB, or ABILITY tags to designate what else is sold. Also, the SHOPINVENTORY or those ITEM, MOB, or ABILITY tags may contain optional PRICE or NUMBER attributes. AFFECT tags: ABILITY tags: CULTURALABILITY tags: BEHAVIOR tags: Required detail: "CLASS" Optional Detail: "PARMS" Optional Details that apply only when this tag applies to a RACE tag: "PROFF" "LEVEL" "QUALIFY" CONTENT tags: Content tags: A pure container tag that contains one or more ITEM tags, as above. EXIT tags: Exit tags: Required detail: "CLASS" Optional Objects: "AFFECT" "BEHAVIOR" Optional Details: "NAME" "DISPLAY" "DESCRIPTION" "DOOR" "LEVEL" "ABILITY" "ISREADABLE" "DISPOSITION" "READABLETEXT" "HASADOOR" "DEFCLOSED" "HASALOCK" "DEFLOCKED" "KEYNAME", "CLOSEWORD", "OPENWORD", "CLOSEDTEXT" RACE tags: Required detail: "CLASS" "NAME" Optional Objects: "WEAPON": tag which should contain an ITEM tag, denoting the creatures natural weapon "RESOURCES": tag which should contain one or more ITEM tags, denoting racial resources "OUTFIT": tag which should contain one or more ITEM tags, denoting the racial outfit "ABILITY" "CULTUREABILITY": same as ABILITY tag, but these are cultural abilities "AFFECT" Optional Details: "CAT" "VWEIGHT" "BWEIGHT" "VHEIGHT" "FHEIGHT" "MHEIGHT" "AVAIL" "LEAVE", "BODYKILL" "AGING" "HELP" "BREATHES" "ARRIVE", "HEALTHRACE" "BODY" "WEAPONRACE" "DISFLAGS" "EVENTRACE" "WEAR" - either a bitmask number, or wear locations names set equal to true to forbid, or false to allow, e.g (mouth=true back=false left_wrist=false) "ESTATS","ASTATS","CSTATS","ASTATE","STARTASTATE" - either a | delimited stat list, or a series of var=value, e.g. (STRENGTH=5 HITS=2 ATTACK=2 etc..) FACTION tags: Required details: "ID" "VALUE"