How To Write Orders

Lists of available orders:

Orders Detailed List (each order described in detail) (as RTF-file)
Orders Concise List (all orders in a concise, tabular fashion)

Interactive Web-Forms for Submitting Turns (you will need request the gamemaster for an activation first)
An Example Order Script

A general explanation of how to write orders:

To make a turn you must do the following:

  • Use the interactive web-form, or:
  • Create an order script using the GPU or an editor and send it via e-mail (turn#cjgames.com) to us.

  1. Order File

    2. Submit your order scripts for Mysticora in a simple text-format (ASCII) with each order on a separate line.
    The order text may be either inside the body of an e-mail or as a separate text file attached to the e-mail. If a text-file is attached the file name must either have the extension"TXT", "ASC" or "MYS". If not, the file will be ignored. The remaining part of the file name is irrelevant,i.e. it may have any name, e.g. "MyMove.TXT". Note that the move files the GPU generates are also simple text files.

    The e-mail is then sent to: turn#cjgames.com with the subject: Mysticora game #'game number'.

    The subject line of this e-mail should contain the game number, e.g. "Mysticora game #1".
    Note that it is also possible to include the turn number if it is behind the game number with intermittent characters, e.g. "Mysticora game #1 turn #27".
    Also note that for security reasons and as protection against spam, when you send an e-mail to the above move address you must use your standard address as registered at CJ Games, other addresses will not be accepted. You may have two e-mail addresses registered as your standard addresses at CJ Games.

    If a player sends in multiple e-mails for an upcoming turn, then the most recent one will be chosen and the others discarded. It is thereby possible for a player to correct his or her turn by simply resending the e-mail with the orders before the upcoming turn deadline.

  2. Order Script Encapsulation

    3. Each order script being submitted must be encapsulated by the starting order "begin_mys"and a the finishing order "end_mys". The beginning order also includes authorization information.No other orders or functions may be on these two lines.
    Example:

    begin_mys(1, 734, "Hans Musterman", 582, "mysecret")
    ....
    end_mys()

    All text before and after these key orders will be ignored by the Mysticora order compiler.

  3. Order Name and Parameters

    4. Almost all player orders or commands have the following format:

    <order-name>(<date>,<retries>,<parameter1>,<parameter2>, ... )

    If the parameters for the number of retries and the game date are left away the program will take the player's default values. As default for a missing date usually the value stored by the set_date command will be used.
    Some commands can even be repeated any number of times, the default value being 0, meaning that the order would only be executed once.
    These would then have the following format:

    

    <order-name>(<date>,<retries>,<repeats>,<parameter1>,<parameter2>, ... )

    A character order would often have the following format:

    <character-order>(<date>, <retries>, <days-spent>, <character-name>, <parameter2>, ...)

    The days spent parameter would mean the number of days (up to 30) that the character would spend doing this action (e.g. training, preparation for an assassination attempt, casting a spell, etc.)

    Please note that time, i.e. the number of days, is the crucial factor which will limit the number of actions you can do. For each turn you will have a limited number of days available (e.g. 5 days in the beta-test game, usually 15 days in the commercial game) for which to complete your orders.

  4. Abbreviation

    5. For each order name there is also an abbreviation containing up to 4 letters. Move files can have both orders with long names or abbreviations.

    Example:

    Explore_Dungeon(...)

    can be abbreviated with:

    EXDU(...)

  5. Compiletime Parameters

    6. The syntax for most common first 3 parameters of an order is standardized. These parameters are also referred to as "compiletime"-parameters, since they are read in at the moment the move file arrives via e-mail (note that this may be far in advance to the actual processing of the move).
    These are named:

    date - The game world date on which this order is first to be executed. If this parameter is left empty then a default date will be assumed. The default datecan be set using the set_date order. If no date is explicitly set using the set_date order then the earlimost possible execution date will be assumed (i.e. the date of order compilation). If a players wants a specific, absolute date then a string should entered in one of the following formats:
    <day number>.<month number>.<year number> or:
    <day number>.<month name>.<year number>
    (instead of a dot as delimiter a slash "/", hyphen "-" or semicolon ":" can also be used)
    Examples: 

    "2.1.501", "02.01.501", "2:1:501", "2-Frost-501", "02/Frost/501"
    Players can also enter relative dates by entering a number instead of a string. That number then will be counted as the number of days past the default date and the date calculated thereby will be used as execution date for that order (only).

    Each scenario will have a separate calendar with their own days, months and years. For a description of the calendar for the first scenario of Mysticora (Nolay Maeg) click here.

    retries - If the order fails, this is the number of subsequent attempts that will be made to execute the order. Note that there will be only 1 attempt per day. If an order fails due to lack of time then this will count towards the number of retries but will not bring the number of retries down to 0. That means an error due to lack of time will never cause an order to be canceled compeletely.

    repeats - When the order is executed successfully this indicates how many more times the order shall be (successfully) executed. Note that there will only be 1 attempt at execution per day.

    The following syntax is used:

    <order-name>([date,[retries,[repeats,]]]param1,param2,...)

    (Note: square brackets will always denote an omittable section of an order in this document)

    IMPORTANT:
    The first 3 compiletime parameters can be left away (or partially: first leaving away repeats, then retries, then date). But in this case program will only properly recognize the first parameter (i.e. param1) if it is a string. That means the parameter must be delimited with quotation marks!
    DO NOT FORGET:
    You should be aware that if you use a pure number for param1 the program will interpret it as one of the first 3 compiletime parameters! That is unless it comes in 4th place.

    Here is an example where the compiletime parameters are not being omitted:

    steal("1-1-500",3,2,"Mathilda","Heinz",1,1,1)

    and here are three valid examples of omitting the compiletime parameters:

    steal(,,,"Mathilda","Heinz",1,1,1)
    steal("Mathilda","Heinz",1,1,1)
    steal("2","Heinz",1,1,1)	(note: Mathilda has id number 2)

    While all orders have the date and retries parameters, some orders may not have the repeats parameters. This is often for such orders where repetition is not reasonable after the initial success of order (e.g. it is not possible to repeat a successful "assassination" since the target would already be dead).

  6. Game Component Parameters

    7. Many parameters will refer to a game component, i.e. a character, a habitation. This can be done either through an id number that each game component will have, or through its name. An order may even allow different game component typesas a parameter. If a player does not specify which game component type is being addressed then the compilerwill look through valid types for this parameter starting with a certain default type (determined individually by each order).
    Example: The move order can be adressed to a group or a character. The default type is a group. If a player writes only "123" as an id number of the game component being ordered to move, then the compiler will first check if there is a group #123.If the player wants to move character #123 although he or she also controls group #123, he or she must then write "c#123".
    These are all the variants of addressing a game component through a parameter:

    "<type code>#<ID>"or:"<type code>#<name>"
    or:
    "#<ID>"
    or:
    "#<name>"
    or:
    "<name>"
    or:
    <ID>

    Examples of trying to address the character John Little, who has the id-number 123:

    "c#123"
    "c#John"
    "#123"
    "#John"
    "John"
    123
    codes for the various game component types
    type code game component type
    c character
    b building
    g group
    h habitation

    Note on character names:
    When referring to a character via his or her name the player may either just use the first name or use the firstname followed by a space and the character's last name. The last name need only be used though if there are possible ambiguities (i.e. the player controls more than one character of that name).
    Also, when referring to a character that does not belong to the player's position, it is inadvisable to justuse the first name. The likelihood of the existance of another character of the same name in the game worldis very high. Using the id-number in such a case is the safest choice.

  7. Order Constants

    8. Order constants must be preceded by a single $-character. Otherwise order constants only contain letter. They are, like order-names, also case insensitive. Internally, the move compiler converts them to a number or string. They are useful because the player then needs not remember abstract numbers.
    For example:

    Instead of writing the (valid) line:

    set_report_verbosity( -1 )

    a player could write:

    set_report_verbosity( $YES )
    Table of Order Constants

  8. Numbers

    9. Parameters that are numbers can be given without "-characters as long as they contain just digits (and the minus-sign). The decimal point is always a dot (this may normally be different in some languages other than English).
    Numbers may also be, e.g. "12%", which is converted to 0.12
    Note that in such a case the quotation marks must be included.

  9. Comments

    10. Comments can be inserted into an order file using a semicolon (";"). Everything to the right of a semicolonwill be ignored by the compiler.

    Example:

    cast_spell(, 1, "Dr Doom", "zal-bel-zal-gogth-nixfor") ;why didn't this work last time?

  10. Function Values

    11. Parameters can also be filled with arithmetic expressions or the return values of functions. These values will (usually) be computed at execution time.

    Example of such a function is the "Order_Successful"-function:

  11. Conditional

    12. Players may use an "IF"-clause to conditionally execute an order. This means the order in the same line will onlybe executed if the function or expression betweent the keyword "if" and the subsequent keyword "then" is true.
    Example:

    if character_status("Bloodblade", "imprisoned?", $YES) then free(, 5, "Shorty Onehand", "Bloodblade", 1, 5)

  12. Lists

    13. Occasionally some orders call for so-called "Lists".
    These have the following syntax:

    <order-name>(<param1>, <param2>, ..., List(<list-element1>,<list-element2>, ...), <paramX>, <paramX+1>, ...)

    These are sort of like a "order within an order".

  13. Execution Duration

    14. When considering how long an order should take to execute, imagine for a moment if someone asked you to do that order, how you would then reply on how much time you would need.
    If you are still unclear then you can either look up the execution duration listed in the orders table or use the following Rule of Thumb:

    Issue only 1 non-trivial order per day.

    Trivial orders are any orders lasting only a few minutes (usually organziational-type actions such as 'transfer_item' or 'join_group'). This rule is per executing game component (character, group) of course.
    On a special note: Training orders should last several days at least to be effective.

The general procedure how moves are submitted and subsequently received:

  1. Turn Cycle

    2. A turn in Mysticora consists of the move a player submits and the subsequent report generated by the Mysticora simulation computer.
    At the end of every work-day, here at CJ Games, the simulation of 1-3 game world days, which includes processing of game moves, will be started. This will usually be around 6 p.m. GMT (Monday-Friday). If a player's e-mail arrives beforehand then it will be included in the simulation run.
    Usually by the next morning the simulation run is finished (it runs about 16 hours) and the reports are sent out.
    There is a minimum time though, usually 1 week, between two turns of a player. If a player submits a move beforehandthen the processing of his or her turn will be postponed accordingly.

    It is important to note that players do not receive the results of their submitted orders immediately, i.e. on the next day. Instead they must usually wait a certain time period, usually 1 week, before they get the results.This is because each order they submit is scheduled to be executed on a certain game world day. This game world day may be any day in the distantfuture of the game world. The player must therefore wait until this day in game world "arrives".
    Each game world day is simulated individually taking many hours for the computer to do so. This can also only be done on work-days because the results must be checked by an operator. During a normal week 5 - 15 game world days will be simulated.

    A player may individually choose how his or her turn schedule runs. A typical player would choose to receive his or herturn on a Saturday morning, so that he or she would have the week-end to read the report and write the next move without losing anytime in the game world (no simulation being run on the week-end). By Sunday evening he or she then would sent out the move.The orders in the move file would then be processed over the course of the week with the report then being sent out onthe next Friday again. And so forth...

  2. Processing of a Single Game Day

    3. Each day of the game world will be simulated individually. Therefore a player's orders will first be grouped together by their game world date. All orders that take more than one day (usually movement orders) will be processed in little parts over the days following that order.

    Next, all the orders for one day will be processed in a random order (i.e. a player position is selected randomly, then one order for this position is processed, then a new player position is selected randomly, etc.).

    Because player turns are given for several days (usually 15 to 30 game days) in advance, this means that they will be processed nearly in parallel. Also, for a unit moving from point A to B this will mean, that if the unit needs more than one day to travel the distance, it will make a stop each day at a certain intermediate point along the way. For this purpose the exact point inside a square at which a unit is currently located will be kept track of to make sure that the movement as a whole takes the correct time and there are no errors for rounding.

  3. Order Success

    4. Players in Mysticora must be aware that if they make orders that depend on the success of many previous orders, that there is a certain chance they will fail due to the effect of cascading errors. But herein lies also great potential for the player who puts a lot of effort into his turns, as he will be able to do many complex things in a single turn. There is also the possibility in Mysticora of giving conditional commands as shown above (e.g. if certain items or groups are present or are in a certain place.). Also, each command has a parameter that determines on how many following days a command will be repeated if an execution failed. A player who makes use of these security mechanisms and avoids very complex command combinations will be able to keep cascading errors to a minimum.

See more on Movement Rules here

 back