When founding an empire the order of operations is first to fetch_captcha. Then create the empire. Then optionally update_species (default is human). Then finally call the found method to set up the empire on it's new home planet.
The following methods are available from /empire.
Returns a 1 if the name is available, or a throws an exception if it is not.
Throws 1000.
The name of the empire to search for.
Ends a session. Returns 1.
Throws 1006.
A session id.
Returns a hash like the following after confirming the password matches the empire.
NOTE: Once established, this session will stick around for up to 2 hours of inactivity. Therefore, you need not login again if you still have a valid session.
{
"session_id" : "id-goes-here",
"status" : { ... }
}Throws 1004 and 1005.
The name of the empire.
The password to authenticate to the empire.
Your client's unique API key, identifiying it from all other clients. See ApiKeys for details.
Retrieves a captcha that is required in order to call the create method. Display the resulting captcha in your creation form and then call create with the user's response.
{
"guid" : "id-goes-here",
"url" : "'https://extras.lacunaexpanse.com.s3.amazonaws.com/captcha/id/id-goes-here.png"
}Creates a new empire and then returns an empire_id.
This is not the end of the story though. Now you must either create a update_species for this empire and then found it, or just skip the species part and found the empire.
Throws 1000, 1001, 1002, and 1014.
NOTE: If either captcha_guid or captcha_solution don't match what the server is expecting it will throw a 1014 error, and the data portion of the error message will contain new captcha information. You must use this. A captcha cannot be used more than once.
A hash of parameters.
The name of the empire to create. Required.
The password to log in to the empire. Must be between 6 and 30 characters. Required unless you have a valid facebook_uid and facebook_token. Still recommended even if you are authenticating using Facebook.
Retyping the password again. This must match password to succeed.
This must match the guid field returned by the fetch_captcha method. Required.
This is the text typed in by the user as the solution of the captcha. Required.
The user's email address. It is not required, but is used for system vital functions like password recovery.
A Facebook user id passed in through Lacuna's Facebook integration system. Optional, but required with the use of facebook_token.
A Facebook access token passed in through Lacuna's Facebook integration system. Optional, but required with the use of facebook_uid.
A 36 character code that was sent to the user by a friend. It is usable only once, and will ensure that their friend gets a home planet that is in relatively close proximity to their home planet.
Set up an empire on it's new home world. Once this method is called, the species can no longer be modified. Returns:
{
"session_id" : "id-goes-here",
"welcome_message_id" : "id-goes-here",
"status" : { ... }
}The welcome_message_id is a message id for a message in the inbox, that starts the tutorial. This is provided so the user can be prompted to read that message right away.
The empire to found.
Your client's unique API key, identifiying it from all other clients. See ApiKeys for details.
Use of the invite code here is deprecated. Please pass in the invite_code in create instead.
Returns a URL that can be pasted into a blog, forum, or whatever to invite friends.
{
"status" : { ... },
"referral_url" : "http://servername.lacunaexpanse.com/#referral=XXXX"
}A session id.
Send an invitation code to a friend so that they can start in the same zone as your empire.
{
"status" : { ... },
"sent" : [
"you@there.com",
...
],
"not_sent" : [
{
"address" : "joe@blow.com",
"reason" : [ 1009, "Someone has already invited that user." ]
},
...
]
}A session id.
The email address of your friend, or a comma separated string of email addresses.
An optional text message that the user can type to invite their friend. This is the default message that will get sent if none is specified:
I'm having a great time with this new game called Lacuna Expanse. Come play with me.After the message, the user's empire name in the game, the friend code, and URI to the server will be attached.
Returns information about the current state of the empire.
NOTE: You should probably never call this method directly, as it is a wasted call since the data it returns comes back in the status block of every relevant request. See "Status" in Intro for details.
{
"server" : { ... },
"empire" : {
"id" : "xxxx",
"colonies" : {
"id-goes-here" : "Earth",
"id-goes-here" : "Mars"
},
"rpc_count" : 321, # the number of calls made to the server
"is_isolationist" : 1, # hasn't sent out probes or colony ships
"name" : "The Syndicate",
"status_message" : "A spy's work is never done.",
"home_planet_id" : "id-goes-here",
"has_new_messages" : 4,
"latest_message_id" : 1234,
"essentia" : 0,
"planets" : {
"id-goes-here" : "Earth",
"id-goes-here" : "Mars",
"id-goes-here" : "Death Star"
},
"tech_level" : 20, # Highests level university has gotten to.
"self_destruct_active" : 0,
"self_destruct_date" : "",
"stations" : {
"id-goes-here" : "Death Star"
},
"primary_embassy_id" : 234567
}
}Throws 1002.
A session id.
Provides a list of the editable properties of the current empire's profile. See also the edit_profile and view_public_profile methods.
{
"profile" : {
"description" : "description goes here",
"status_message" : "status message goes here",
"medals" : {
"id-goes-here" : {
"name" : "Built Level 1 Building",
"image" : "building1",
"date" : "01 31 2010 13:09:05 +0600",
"public" : 1,
"times_earned" : 4
},
...
},
"city" : "Madison",
"country" : "USA",
"notes" : "notes go here",
"skype" : "joeuser47",
"player_name" : "Joe User",
"skip_happiness_warnings" : 0,
"skip_resource_warnings" : 0,
"skip_pollution_warnings" : 0,
"skip_medal_messages" : 0,
"skip_facebook_wall_posts" : 0,
"skip_found_nothing
"skip_excavator_resources" : 0,
"skip_excavator_glyph" : 0,
"skip_excavator_plan" : 0,
"skip_spy_recovery" : 0,
"skip_probe_detected" : 0,
"skip_attack_messages" : 0,
"skip_incoming_ships" : 0,
"email" : "joe@example.com",
"sitter_password" : "abcdefgh" # never give out your real password, use the sitter password
},
"status" : { ... }
}A session id.
Edits properties of an empire. Returns the view_profile method. See also the view_profile and view_public_profile methods.
Throws 1005, 1009.
A session id.
A hash reference of properties to be edited. You may set one or all of the profile properties in this hash reference. Only those set will be updated.
A description of the empire. Limited to 1024 characters and cannot contain < or >.
An email address that can be used for system functions like password recovery. Must either resemble an email address or be empty.
A password that can be safely given to account sitters and alliance members. Must be between 6 and 30 characters.
A message to indicate what you're doing, how you're feeling, or other status indicator. Limited to 100 characters, cannot be blank, and cannot contain @, &, <, >, or ;.
An optional text string of the city in which the player resides. Limited to 100 characters and cannot contain @, &, <, >, or ;
An optional text string of the country in which the player resides. Limited to 100 characters and cannot contain @, &, <, >, or ;
A text blob where the user can write down whatever they want to store in their account. Limited to 1024 characters and cannot contain @, &, <, >, or ;
An optional text string of the username this player uses on skype. Limited to 100 characters and cannot contain @, &, <, >, or ;
An optional text string of the real name or online identity of this player. Limited to 100 characters and cannot contain @, &, <, >, or ;
An array reference of medal ids that the user wishes to display in the public profile.
Defaults to 0. Set to 1 if the user no longer wants to receive messages about unhappy citizens.
WARNING: These messages are there for your own protection. Turn off at your own risk.
Defaults to 0. Set to 1 if the user no longer wants to receive messages about a lack of resources to keep their buildings running.
WARNING: These messages are there for your own protection. Turn off at your own risk.
Defaults to 0. Set to 1 if the user no longer wants to receive messages about excess waste causing pollution.
WARNING: These messages are there for your own protection. Turn off at your own risk.
Defaults to 0. Set to 1 if the user no longer wants to receive messages about the medals they've earned.
Defaults to 0. Set to 1 if the user no longer wants messages to be posted to their Facebook wall.
Defaults to 0. Set to 1 if the user no longer wants to receive messages when excavators find nothing.
Defaults to 0. Set to 1 if the user no longer wants to receive messages when excavators find resources.
Defaults to 0. Set to 1 if the user no longer wants to receive messages when excavators find glyphs.
Defaults to 0. Set to 1 if the user no longer wants to receive messages when excavators find plans.
Defaults to 0. Set to 1 if the user no longer wants to receive spy recovery messages. ("I'm ready to work. What do you need from me?")
Defaults to 0. Set to 1 if the user no longers wants to receive messages when a probe is detected.
Defaults to 0. Set to 1 if the user no longers wants to receive messages about attacks.
Controls the display of incoming ships (Own, Allied, Foreign) on your map display. Defaults to 0 (shows ships). Set to 1 if you want to hide incoming ships (can improve response of browser).
Provides a list of the data that's publicly known about this empire.
{
"profile" : {
"id" : "empire-id-goes-here",
"name" : "Lacuna Expanse Corp",
"colony_count" : 1,
"status_message" : "Looking for Essentia."
"description" : "We are the original inhabitants of the Lacuna Expanse.",
"city" : "Madison",
"country" : "USA",
"skype" : "joeuser47",
"player_name" : "Joe User",
"medals" : {
"id-goes-here" : {
"name" : "Built Level 1 Building",
"image" : "building1",
"date" : "01 31 2010 13:09:05 +0600",
"times_earned" : 4
},
...
},
"last_login" : "01 31 2010 13:09:05 +0600",
"date_founded" : "01 31 2010 13:09:05 +0600",
"species" : "Lacunan",
"alliance" : {
"id" : "id-goes-here",
"name" : "The Confederacy"
},
"known_colonies" : [
{
"id" : "id-goes-here",
"x" : "1",
"y" : "-543",
"name" : "Earth",
"image" : "p12-3"
},
...
]
},
"status" : { ... }
}Throws 1002.
A session id.
The id of the empire for which you'd like to retrieve the public profile.
Starts a password recovery process by sending an email with a recovery key.
A hash of options to recover a password. Choose one.
The unique id of the empire to recover.
The full name of the empire.
The email address associated with an empire.
Change the empire password that has been forgotten.
{
"session_id" : "id-goes-here",
"status" : { ... }
}A key that was emailed to the user via the send_password_reset_message method.
The password to log in to the empire. Required. Must be between 6 and 30 characters.
Retyping the password again. This must match password1 to succeed.
Your client's unique API key, identifiying it from all other clients. See ApiKeys for details.
Change the empire password.
A session id.
The password to log in to the empire. Required. Must be between 6 and 30 characters.
Retyping the password again. This must match password1 to succeed.
Find an empire by name. Returns a hash reference containing empire ids and empire names. So if you searched for "Lacuna" you might get back a result set that looks like this:
{
"empires" : [
{
"id" : "id-goes-here",
"name" : "Lacuna Expanse Corp"
},
{
"id" : "id-goes-here2",
"name" : "Lacuna Pirates"
}
],
"status" : { ... }
}A session id.
The name your searching for. It's case insensitive, and partial names work fine. Must be at least 3 characters.
Sets the empire status message. Similar to what you might put on your Facebook wall, or in a tweet, but about your empire.
A session id.
A message to indicate what you're doing, how you're feeling, or other status indicator. Limited to 100 characters, cannot be blank, and cannot contain @, &, <, >, or ;.
Shows the dates at which boosts have expired or will expire. Boosts are subsidies applied to various resources using essentia.
{
"status" : { ... },
"boosts" : {
"food" : "01 31 2010 13:09:05 +0600",
"ore" : "01 31 2010 13:09:05 +0600",
"energy" : "01 31 2010 13:09:05 +0600",
"water" : "01 31 2010 13:09:05 +0600",
"happiness" : "01 31 2010 13:09:05 +0600",
"storage" : "01 31 2010 13:09:05 +0600",
"building" : ""01 31 2010 13:09:05 +0600"
"spy_training_boost" : ""01 31 2010 13:09:05 +0600"
}
}A session id.
Spends 5 essentia, and boosts storage (all 5 types) on all planets for 7 days. If a boost is already underway, calling again will add 7 more days.
{
"status" : { ... },
"storage_boost" : "01 31 2010 13:09:05 +0600"
}Throws 1011.
A session id.
Spends 5 essentia, and boosts food production on all planets for 7 days. If a boost is already underway, calling again will add 7 more days.
{
"status" : { ... },
"food_boost" : "01 31 2010 13:09:05 +0600"
}Throws 1011.
A session id.
Spends 5 essentia, and boosts water production on all planets for 7 days. If a boost is already underway, calling again will add 7 more days.
{
"status" : { ... },
"water_boost" : "01 31 2010 13:09:05 +0600"
}Throws 1011.
A session id.
Spends 5 essentia, and boosts energy production on all planets for 7 days. If a boost is already underway, calling again will add 7 more days.
{
"status" : { ... },
"energy_boost" : "01 31 2010 13:09:05 +0600"
}Throws 1011.
A session id.
Spends 5 essentia, and boosts ore production on all planets for 7 days. If a boost is already underway, calling again will add 7 more days.
{
"status" : { ... },
"ore_boost" : "01 31 2010 13:09:05 +0600"
}Throws 1011.
A session id.
Spends 5 essentia, and boosts happiness production on all planets for 7 days. If a boost is already underway, calling again will add 7 more days.
{
"status" : { ... },
"happiness_boost" : "01 31 2010 13:09:05 +0600"
}Throws 1011.
A session id.
Spends 5 essentia, and boosts build queues on all planets for 7 days. If a boost is already underway, calling again will add 7 more days. It will not boost builds currently under way, only new builds added to a build queue.
{
"status" : { ... },
"building_boost" : "01 31 2010 13:09:05 +0600"
}Throws 1011.
A session id.
Spends 5 essentia, and boosts spy training speed on all planets 50% for 7 days. If a boost is already underway, calling again will add 7 more days. Unlike other boosts, this one will boost spies currently in specialist training.
{
"status" : { ... },
"spy_training_boost" : "01 31 2010 13:09:05 +0600"
}Throws 1011.
A session id.
Enables a destruction countdown of 24 hours. Sometime after the timer runs out, the empire will vaporize.
{
"status" : { ... }
}A session id.
Disables the self distruction countdown.
{
"status" : { ... }
}A session id.
Redeems an essentia code and applies the essentia to the empire's balance.
{
"status" : { ... }
}A session id.
A 36 character string that was sent to the user via email.
Updates the empire's species and returns 1. Can only be called after create has been called and before found has been called. Before or after that will throw an exception. If you have already founded your empire then use redefine_species.
See also: get_species_templates
Throws 1000, 1002, 1005, 1007, 1008, 1009, and 1010. The data parameter will contain the field name that needs to be adjusted, if it can be attributed to a single field.
The id of the empire you wish to update a species for.
A hash reference of parameters. With the exception of name and description, the parameters are all integers. When added together they must equal 45.
The name of the species. Limited to 30 characters, cannot be blank, and cannot contain @, &, <, >, or ;. Required.
The species description. Limited to 1024 characters and cannot contain < or >.
An integer between between 1 and 7, inclusive, where 1 is closest to the star. Each value between min_orbit and max_orbit, inclusive, count as a point toward the max of 45. min_orbit must be less than or equal to max_orbit.
An integer between between 1 and 7, inclusive, where 1 is closest to the star. Each value between min_orbit and max_orbit, inclusive, count as a point toward the max of 45. max_orbit must be greater than or equal to min_orbit.
An integer between 1 and 7 inclusive, where 7 is best. Determines species advantages manufactured goods, such as ships.
An integer between 1 and 7 inclusive, where 7 is best. Determines species advantages in spying.
An integer between 1 and 7 inclusive, where 7 is best. Determines species advantages in upgrading buildings.
An integer between 1 and 7 inclusive, where 7 is best. Determines species advantages in the speed of building.
An integer between 1 and 7 inclusive, where 7 is best. Determines species advantages in food production.
An integer between 1 and 7 inclusive, where 7 is best. Determines species advantages in mineral production.
An integer between 1 and 7 inclusive, where 7 is best. Determines species advantages in energy, propultion, and other technologies.
An integer between 1 and 7 inclusive, where 7 is best. Determines species advantages in waste and water management.
An integer between 1 and 7 inclusive, where 7 is best. Determines species advantages in managing population happiness.
An integer between 1 and 7 inclusive, where 7 is best. Determines species advantages in freight handling.
An integer between 1 and 7 inclusive, where 7 is best. Determines species advantages in colonization.
Defines the extra limits placed upon a user that want's to redefine their species.
{
"status" : { ... },
"essentia_cost" : 100, # cost to redefine the species
"max_orbit" : 2, # maximum settable orbit
"min_orbit" : 5, # minimum settable orbit
"min_growth" : 4, # minimum for growth affinity
"can" : 0, # whether or not they can redefine their species
"reason" : "You have already redefined your species in the past 30 days."
}A session id.
Allows a user to spend essentia and redefine their species affinities, name, and description. This can only be used after the empire has been founded. If you want to redefine the species during empire creation then see update_species.
See also redefine_species_limits.
{
"status" : { ... }
}WARNING: Once this is done it cannot be redone for 1 month, so make sure the user is aware of this and prompt them appropriately before submitting the request.
A ssession id.
See the params list in the update_species method.
Returns a list of the stats associated with an empire's species as it was originally created. An empire can only view it's own species stats through this method.
{
"species" : {
"name" : "Human",
"description" : "The descendants of Earth.",
"min_orbit" : 3,
"max_orbit" : 3,
"manufacturing_affinity" : 4,
"deception_affinity" : 4,
"research_affinity" : 4,
"management_affinity" : 4,
"farming_affinity" : 4,
"mining_affinity" : 4,
"science_affinity" : 4,
"environmental_affinity" : 4,
"political_affinity" : 4,
"trade_affinity" : 4,
"growth_affinity" : 4
},
"status" : { ... }
}Returns an array ref of species templates that can be used to help the user populate the form for update_species.
[
{
"name" : "Average",
"description" : "A race of average intellect, and weak constitution.',
"min_orbit" : 3,
"max_orbit" : 3,
"manufacturing_affinity" : 4,
"deception_affinity" : 4,
"research_affinity" : 4,
"management_affinity" : 4,
"farming_affinity" : 4,
"mining_affinity" : 4,
"science_affinity" : 4,
"environmental_affinity" : 4,
"political_affinity" : 4,
"trade_affinity" : 4,
"growth_affinity" : 4
},
...
]