Sunday, February 3, 2013

Worldsim web application tutorial

Last updated: Feb 3, 2013

Figure 1: How the app looks when you log in

When you log in to worldsim, you are presented with a window that looks like the figure 1.  On the very top right it you can see what turn it is, in this case turn 1, when the turn is scheduled to end, Feb 8, and there is a logout button.  Between turns, there will also be a big red capitalized "LOCKED".  This lets you know that the game is between turns, and many game actions are prohibited, such as making policies, and treaties.  Any actions made when the game is locked are not guaranteed to be read by the admin, and won't count as "official" (most of these actions will be refused by the server, but it's possible that I didn't block all the actions I should have).

The worldsim program is divided up into "windows" (I may also sometimes refer to them as "views").  The big dark grey rectangle near the top of the screen lets you select which windows are open.  There are two kinds of windows, "toggle" windows, and "swap" windows.  The toggle windows are "Mail", "Resources", and "Users".  These windows can share the screen with any other toggle windows, and with a "swap" window.  The other windows are swap windows, there can only be one swap window up at a time.  Clicking the name of a toggle window will toggle it on or off.  Clicking the name of a swap window will turn off the current swap window and turn on the one you clicked.

At the bottom of the screen is the chat bar.

Now I'll explain each of the windows individually.

Figure 2: the cover window

The cover window lists general information about your country, the news for the turn, and research results.  News tells you important events going on in your country that you should react to this turn.  Research results tell you about technical advances achieved from allocating R&D the previous turn.
This view is not interactive, and will not change during the turn.


Figure 3: the map window

The map window shows a map of the world, and world news.  The map window is the same for all players.  Everybody sees the same map and the same world news.  Most turns, the world news will include a listing of "WPI" values.  WPI is short for World Price Index.  Each tradable resource has a WPI, the WPI is calculated by a complicated formula comprehensible only to the worlds best economists, but the WPI value for any given resource is usually close to the average purchasing price for that resource among all countries.  If you can buy a resource for less than the WPI, it might be a good idea to try to trade that resource to other countries,  likewise if it costs you more than the WPI to buy a resource it might be cheaper for you to get that resource through trading.



Figure 4: Make Offer window

The make offer window is where you propose trades.  Under the text "Active Offers" is a list box that lists trades you are currently proposing.  The name listed is a summary of the trade, every word in the name starts with "O" for "out" or "I" for "in", followed by a number, and the first three letters of a resource name.  For the trade listed in fig 4, you can see just by the name "O1kru I4poi" that this trade involves selling 1 krust to another country in return for 4 points.  To stop offering a trade, select it and click the "Delete" button.  To see more details about a trade click the "View" button.
Clicking the view button will modify the bottom part of the window to match the currently selected Active offer.  You can't change the terms of an Active offer, but you can view it, delete it, change the terms, and then resubmit the modified version.

Targets lists all the countries with checkboxes next to their names.  A checkbox corresponds to the country name to the right of the checkbox.  By default, the checkboxes of your "trade partners" will be selected,  a trade partner is a country where you have an embassy, and that has an embassy in your country.  Trades can only be executed between trade partners, but you can propose a trade to anybody, and then execute the trade once both countries have embassies.

The "All", "Partners" and "None" buttons change which boxes are selected (in hopefully obvious ways).

Below that are the terms of the trade.  Terms can be selected and deleted with the "Delete Terms" button.  Note that this will not remove terms from an active trade (as explained above).  If a term is listed as "In" then that resource will enter your country when the another country accepts the trade.  If a term is listed as "Out" then that resource will be sent to the other country.

You can add terms to a trade with the next group of buttons.  The first drop down menu lets you select whether the resource will enter ("In") or leave ("Out") your country.  In the blank space, write in a positive integer for the amount of that resource to change hands.  In the final drop down, you can choose which resource the term involves.

Sometimes you can trade out resources that you don't have any of.  If the "Buy resources to meet demand" is checked, your country will automatically spend points to buy the resource if another country accepts the trade, but you don't have enough of the "out" resources in stock to cover the trade.  This option is off by default, but it can be useful if you are trading a resource for more points than it costs you to create that resource.  Be wary though, you can easily run out of a resource and be below your minimum at the end of the turn if you aren't careful (but you'll probably have enough points to buy up to your minimum, just be sure to check near the end of the turn).

"Number of trades" is how many times a trade can be accepted before it automatically disappears.  If you are selling some resource, you may want to set this to an arbitrarily high number, like 10000, but if you are just trying to buy up to your minimum, you will want to keep this at some low number.  It defaults to 1.
Figure 5: View offers window

The view offers window is where you can see which trades are being proposed by other countries.  The first list box lists the trades being offered.  The first word in the name of a trade is the first four letters of the name of the country offering the trade.  The next part of the name has a code that is just like the one in the "Make offers" view (See above).  Selecting a trade name and clicking "view" will make the bottom part of the window show more details about the trade.  "Source" is the full name of the country offering the trade.  If you do not mutually share embassies with that country big red letters saying "Not Trade Partners" will appear, letting you know that you won't actually be allowed to accept this trade until embassies are established.  Next are the terms of the trade.  Note that these terms are relative to the country offering the trade (and not relative to your country),  therefore when it says "In", that resource will actually leave your country and go "In" to the offering country.  Likewise when it says "Out", those resources will enter your country.  (This might be a little confusing, I had trouble thinking of unambiguous terminology for this view, if you have suggestions, please let me know).


Figure 6: Policies window

The policies window has several functions.  It is where you buy resources and describe most of the country's internal policies.  A policy consists of a name, a description and associated actions.  Every policy should have a name (even if it is a simple one like "buy edibulls"). If a policy doesn't have a name it will be hard to see it in the list when you save or enact it.  Most policies will also have descriptions and associated actions, but some may lack one or the other of them.  The description explains in words what the policy's goals and execution strategy are.  If the description is obvious, like "buy edibulls to meet minimums", it can be omitted, but there may be an advantage to writing something clever even for mundane policies, perhaps (maybe something like "buy edibulls to meet minimums, instructing farmers to keep a close watch for signs of crop diseases", if there has been a recent outbreak in your country).  When buying units that aren't tradable resources, a description is mandatory (see the description in fig 6).

Three kinds of actions can be associated with a policy, "Buy", "Liquidate", or "Allocate".  "Buying" a resource will exchange points for units of that resource.  "Liquidating" will exchange a resource for points (note that some resources that can be liquidated do not give you any points when they are liquidated, but you may have political reasons to liquidate them).  "Allocating" a resource means designating that amount of resources to make the policy more effective.  Except for R&D, allocated resources are spent, and do not come back the next turn.  The most common resources to allocate are points and R&D, but other kinds of resources can be spent if appropriate.  It does not make sense to allocate resources such as Economy, People, Health, or Culture, in most cases, if you think you need to allocate these resources, what you actually should be doing is "Buying" them.  Also, military units cannot be allocated in the "Policies" window because there is a special window dedicated for military moves (see below).

After a description has been written and actions added, a policy can be either "Saved" or "Enacted".  A saved policy is not yet official, saving just lets you archive a policy that you think you might want to enact later.  Saved policies can be viewed, edited and enacted later if desired.  Enacting a policy makes the policy official.  All policies that have been enacted when the turn ends will be considered official and will affect what changes happen to your country during the turn transition.  Some policies can be "unenacted" with the "Request Removal" button without consequence as long as the game is not locked.  Policies involving buying or liquidating resources, however, cannot be removed once enacted, so be careful when making these policies.

Figure 7: Taxes window

The taxes window is similar the policies window, except that it has a more narrow focus.  All tax policies must have a name, a description, and a "Target revenue".  The description tells what the tax will be on, and possibly how it will be collected, and other details you deem important.  "Target revenue" is how many points you expect your government to make from the tax.  It is important to realize that this is just a "Target", depending on the description you provide, your government may not make as much as you expect (for example if you try to make hundreds of points off of taxing some activity that isn't very common), less often, you might make more money than you expect.

"Total Expected Revenue" is the sum of the revenues from all of your taxes.

It is possible to have nominal taxes or "negative" taxes, for political reasons, but these kinds of policies could also be submitted in the "Policies" window.

Taxes can be added or removed freely up until the turn ends.




Figure 8: Treaties window.  A new treaty being written (left).  A treaty that has been submitted and has parties with various statuses (right)

A treaty is a policy that is shared between two or more countries.  A treaty consists of a name, a description, and a list of countries.  Each country in the list has one of three statuses. It has either made no action involving the treaty ("Pending"), signed the treaty ("Signed"), or withdrawn or declined the treaty ("Withdrawn or Declined").  In most cases, only countries with the status "Signed" when the turn ends will be considered party to a treaty (although signing and then withdrawing, or refusing to sign can have consequences depending on the treaty).  Exchange of physical goods such, like points and tradable resources agreed to in a treaty must be executed via the "make offers" and "view offers" windows.  Exchange of more abstract things like technology will occur between turns among the countries who are "signed" when the turn ends.

To propose a new treaty, click "New Treaty", then enter the name and text, then add countries by highlighting their names and pressing the "-->" button.  Countries can be removed by highlighting their name in the "Parties" list and pressing the "<--" button.  The country proposing a treaty must be a party to it (you can't remove yourself from the parties list), and will sign it automatically upon submitting.  Pressing submit will put the treaty in the "Pending" list of all party countries.  When a treaty is submitted, party countries will receive a chat message telling them someone has proposed a treaty to them.

You can sign a treaty by clicking its name in the "Pending" list, and then clicking "View", and finally "Sign", which will be next to "New Treaty".  You must view a treaty before signing it, but you can decline or withdraw from a treaty just by selecting its name in the singed or pending list, and then clicking "withdraw" or "decline".  When your status changes, other parties of the treaty will be sent a chat message.

Once you have declined or withdrawn from a treaty, you cannot resign the same treaty, if you want to be a party, you will have to propose a new treaty and hope that all of the countries that were members of the old one agree to be members of the new one too.



Figure 9: Embassies window

The embassies window is where you establish embassies in other countries and allow them to establish embassies in your country.  To establish an embassy you must have a certain number of Political Diplomacy (PD) units allocated to a country.  The exact number of units you need depends on the history between your country an another country.  You can allocate, or remove PD units from a country using the "+1" and "-1" buttons in the same line as that country.  It can be advantageous to have more than the minimum number of PD points for an embassy allocated to a country, it can also be advantageous to allocate PD points to countries you don't have an embassy in.  Be careful though, allocating PD units removes them from your "current" pool, and may put you below your minimum (see the FAQ for more details on why this might be bad).  To have an embassy, you must have enough PD points allocated, then you must "Request" an embassy, and the country where you request the embassy must "accept" your request.  You can expel an embassy from your country whenever you want, and you can also withdraw your embassy from other countries whenever you want.


Figure 10: Military window

The military view is where you make policies involving deploying military units.  A military policy has a name, a "Public Reason", a "Real Reason", and list of assigned units.  The "Public Reason" is the reason your country announces publicly for why they are moving around thousands of troops.  The "Real Reason" describes what your troops will actually be equipped for and try to execute.
Assigned units are how many of each kind of military unit assigned to the mission.

In most cases, the "Public Reason" will be announced to the world via chat, or an update to the world map.  But this does not happen automatically, so covert operations can also be described in the Military window.  Note, however, that each single unit of military represents thousands of troops, for smaller scale operations, and particularly spying (which requires R&D to be allocated), you can use the Policies window, and allocate points.

Troop movements require approval from an Admin to become fully deployed, or to withdraw from combat once active.  the "Deploying" list is a list military actions that you have submitted, but have not yet been approved.  Once approved, they will move into the "Active" list.  To cease an active operation, select it and press "Withdraw", this will  move it into the "Withdrawing" list, and to complete withdrawing, the withdrawal will have to be approved by an admin.

Figure 11: Download window

The download window allows you to access all the data for your country in a format that can be pasted into Excel, or read by other software.  It also gives you access to data about your country in previous turns.  You can completely ignore the Download window, and still be an effective worldsim player.  It's just here for the geeks, and other people who want to analyze the data about their country in ways that are difficult in the web interface.


Figure 12: Mail window

The mail window is where you send and receive private messages.  The interface is a lot like the treaties window.  You add and remove recipients with the left and right arrow buttons.  And send with the "Send" button.  You can send messages to your own country (potentially useful if you have a team of more than one person) or to the Admin.  All messages should have both a name and text.


Figure 13: Chat

The chat bar sits at the bottom of the screen.  The chat bar shows three kinds of messages: chat between players, game events, and "errors".  Chat between players is always "global", meaning that when you send a chat message, it shows up in everybody's chat window.  For private messages, use the "Mail" window.  Game event messages include messages to tell you when someone has requested an embassy in your country, or when a treaty has been signed, or a trade has been executed.  Gane event messages are usually not global, but they can be, for example if someone signs a treaty that every country is a party to.   "Error" messages are messages specific to a user, they tell when a requested action fails, for example if you try to accept a trade from a country you have no embassy it.  The message you get when you send a "Mail" is also considered an "error message" even though it isn't really an error.  Error messages go away when you log out, and are never seen by your teammates.

There are a few options to change what appears in the chat window.  To see these options, press the button with the asterisk "*" on it, at the far right hand side of the chat bar.

You can minimize the chat window with the "-" button at the bottom left of the chat bar. Press it again to bring chat back up.


 Figure 14: Resources window

The resources window tells you all about your points and resources.  "Start" tells you how many of that resource you started the round with.  "Current" tells you how many units are in your country right now.  "Min" tells you how many units must be in your country at the end of the turn to avoid possible negative consequences.  "Cost" is how many points it costs to buy the resource (using the policies view).  "Scrap" is how many points you get for liquidating a resource.

Boxes in the "Current" column can have different colors.  The text is green if you are above minimum, red if you are below, and black if you are at minimum.




Figure 15: User Data window

The user data window gives you information about the players of the game.  The column names are self explanatory.



Ok, that's it for now.  Let me know if anything needs more explanation.