[REFERENCE] Creating a game through the API [63180]

Discussion in 'Mod Discussions' started by wondible, February 28, 2014.

  1. wondible

    wondible Post Master General

    Messages:
    3,315
    Likes Received:
    2,089
    Merged into PADOCS, which will probably be a more convenient place to update it, especially now that the full thing has overflowed the allowed message size.

    https://github.com/Noah-Huppert/PA-Documentation

    (I'm leaving this in markdown for the moment to get something out, I may revisit formatting later)

    Updates made for 63180, but this will always be a work in progress.

    ## Index
    - Super high level overview
    - Overview of API calls
    - Description of starting a game
    - Data structures
    - API methods
    - Handlers Used

    ## Super high level overview:
    - Request a server from UberNet
    - Attach to the server and wait for a state change
    - Configure the game
    - Players join armies
    - Wait for the server to be ready
    - Start the game
    - Wait for a state change

    ## Overview of API calls:

    Heading is the scene in PA.

    ### connect_to_game:
    - engine ubernet.startGame/ubernet.joinGame
    - engine join_game
    - handlers.login_accepted
    - app.hello
    - handlers.server_state payload.url

    ### new_game:
    - send_message modify_settings with an object
    - send_message modify_system with a server-formatted system
    - send_message reset_armies with armies
    - optionally: add_army, remove_army, leave_army, modify_army, next_primary_color, next_secondary_color, chat_message, update_commander, leave
    - send_message join_army
    - send_message toggle_ready
    - handlers.control payload.sim_ready == true
    - send_message start_game
    - handlers.server_state payload.url

    ## Starting a Game

    ### Request a server from UberNet

    A game requires a server. The only servers we have available right now are UnberNet servers. You can request a new server from UberNet, or request to join an existing instance.

    engine.asyncCall("ubernet.startGame", model.uberNetRegion(), 'Config').done(function (data) {
    data = JSON.parse(data);
    model.lobbyId(data.LobbyID);

    // continue
    }).fail(function (data) {
    console.log("failed to start ubernet game");
    reset();
    });

    The method returns a promise with .done and .fail methods. The payload object passed to the done handler provides a LobbyID which might be of use if you want to connect certain other clients to the same game.

    If you are joining a game someone else has created, you will need the LobbyID.

    engine.asyncCall("ubernet.joinGame", lobbyId).done(function (data) {
    data = JSON.parse(data);

    if (data.PollWaitTimeMS) {
    // wait and then recurse
    } else {
    console.log("ubernet game join successful, will connect now");
    // continue
    }
    }).fail(function (data) {
    console.log("failed to join ubernet game");
    reset();
    });

    The reset method calls one additional engine method, which is used to help ensure the game stays in a consistent state.

    engine.call('reset_game_state');

    ### Connect to a server

    Once you've either created a server or registered your status with UberNet, you need to connect tot he server itself (presumably this is where a local server would pick up)

    engine.call('join_game',
    String(data.ServerHostname),
    Number(data.ServerPort),
    String(model.displayName()), // the user's name
    String(data.Ticket),
    String(JSON.stringify({ password: undefined })));

    After issuing this call, listen for a login_accepted event. This is where alpha-ui shows the transmit message.

    app.hello(handlers.server_state, handlers.connection_disconnected);

    listen to handlers.server_state for msg.state == 'lobby'

    ### Configuring the Game

    Once you've joined the game, it must be configured. See the data structures below for fields in a settings object and system. An important detail is that system format used by the client and server slightly different, and may need to be translated.

    model.send_message('modify_settings', settings, optionalCallback)
    model.send_message('modify_system', system, optionalCallback)

    The army information was recently moved out of the game description to a number of detailed methods. If you know exactly what you want to make, call reset_armies

    var armies = [
    { "slots" : 1, ai: false, alliance: false},
    { "slots" : 1, ai: true, alliance: false, economy_factor: -1 }
    ]

    model.send_message('reset_armies', armies, optionalCallback)

    If you are less certain of the situation, you may also use add_army, modify_army, and remove_army.

    ### Players join armies

    Once the game is configured, players may join armies.

    model.send_message('join_army', {
    army: slot, // army index
    commander: { ObjectName: model.preferredCommander().ObjectName }
    });

    Once a player has joined an army (the methods accept no parameter to say otherwise), the player may call next_primary_color, next_secondary_color, or update_commander. In theory chat_message is available as soon as you've joined a game.

    ### Start the game

    Players need to send the toggle_ready message before the game may begin. The server must be in the sim_ready state, which can be observed on handlers.control

    Once all players and the server are ready, the host may start the game by sending start_game. Failure due to misconfiguration is common here, so make sure to report errors on this method.

    model.send_message('start_game', undefined, function(success) {
    if (!success) {
    console.log('start_game failed')
    reset()
    }
    });

    All you can do from there is wait for the server_state message with payload.state == 'landing' and follow the payload.url. If you are spectating, the state will be 'playing' instead.
    Last edited: March 21, 2014
    tatsujb, cola_colin and LavaSnake like this.
  2. wondible

    wondible Post Master General

    Messages:
    3,315
    Likes Received:
    2,089
    The 'type' field sent by new_game is a string.
  3. wondible

    wondible Post Master General

    Messages:
    3,315
    Likes Received:
    2,089
    So mostly I'm an idiot. I didn't switch the stuff that happens on server_state config to server_state lobby.
  4. wondible

    wondible Post Master General

    Messages:
    3,315
    Likes Received:
    2,089
    So far no luck with economy modifiers though, it may be a server issue.
  5. stormingkiwi

    stormingkiwi Post Master General

    Messages:
    3,266
    Likes Received:
    1,355
    There was an instant sandbox mode? Sweet!
  6. wondible

    wondible Post Master General

    Messages:
    3,315
    Likes Received:
    2,089
  7. wondible

    wondible Post Master General

    Messages:
    3,315
    Likes Received:
    2,089
  8. wondible

    wondible Post Master General

    Messages:
    3,315
    Likes Received:
    2,089
    62110: Code inspection says that economy_factor is an extra field when configuring armies (peer of slots, ai, alliance)
  9. wondible

    wondible Post Master General

    Messages:
    3,315
    Likes Received:
    2,089
    First attempt failed.
  10. wondible

    wondible Post Master General

    Messages:
    3,315
    Likes Received:
    2,089
    economy_factor is ignored if it's 0, or attached to player army. AI values can be arbitrarily small or negative.
  11. cptconundrum

    cptconundrum Post Master General

    Messages:
    4,186
    Likes Received:
    4,900
    :eek: Why would they do that!!???
  12. wondible

    wondible Post Master General

    Messages:
    3,315
    Likes Received:
    2,089
    Possibly value coercion?
  13. cola_colin

    cola_colin Moderator Alumni

    Messages:
    12,074
    Likes Received:
    16,221
    I did not see this thread at all before just now.
    xD
    Some of your stuff could have helped me.
    But yeah I figured it out by myself now.

    The issues I encountered where mostly the renamed calls to some engine methods (wtf).
    If you want to connect to a game with another client by lobby id you need to make sure to have the game configured by the host already. Oherwise you will get "please wait" answer.
    Uber's code only lists configured games, so they don't handle that case at all.

    Additionally some of the dataformats changed so my data grabbing failed by js errors a few times and the loading phase now is entered by a handler like this one:

    Code:
        handlers.control = function(payload) {
            if (payload.starting) {
               
                window.location.href = 'coui://ui/alpha/building_planets/building_planets.html';
            }
        };
    It does not wait for other players to finished loading anymore as far as I can tell.

    Building planets is a very small scene that just waits for a server_state message that tells it to switch to live_game
    thetrophysystem likes this.
  14. wondible

    wondible Post Master General

    Messages:
    3,315
    Likes Received:
    2,089
    I thought that's what @ mention was for. If that doesn't work I'll PM next time.
  15. cola_colin

    cola_colin Moderator Alumni

    Messages:
    12,074
    Likes Received:
    16,221
    I don't think it works like that.
    thetrophysystem likes this.
  16. cptconundrum

    cptconundrum Post Master General

    Messages:
    4,186
    Likes Received:
    4,900
    My guess is they are handling this in server-side javascript and trying to do a check to see if the value has been given to them. Someone thought they could check if it is undefined with if(ecoModifier) and forgot that 0, false, and undefined all fail that check. Maybe we can get them to fix it.
  17. cola_colin

    cola_colin Moderator Alumni

    Messages:
    12,074
    Likes Received:
    16,221
    The latest patch removed armies from the game description and requires them via an extra send_message.
    With that it works ... sometimes.

    EDIT:
    sometimes meaning that I am getting stuff like "login rejected"
    Never saw that before when setting games up myself.
    thetrophysystem likes this.
  18. wondible

    wondible Post Master General

    Messages:
    3,315
    Likes Received:
    2,089
    Maybe the servers will still transitioning over to the new build?
  19. cola_colin

    cola_colin Moderator Alumni

    Messages:
    12,074
    Likes Received:
    16,221
    Don't think that would be that case.
    Whatever it was, it has stopped now.
    thetrophysystem likes this.
  20. wondible

    wondible Post Master General

    Messages:
    3,315
    Likes Received:
    2,089
    I'm planning to turn this thread into a reference. Here is the original post for posterity.

    I'm basically opening this up in the hopes that me and Cola_Colin can cooperate on fixing things up for Gamma. I was pretty dependent on the AI0 games for testing live_game mods and Instant Sandbox predictably broke.

    Here is my clif notes for Beta:

    connect_to_game:
    engine ubernet.startGame
    engine join_game

    new_game:
    send_message game_config with desc
    handler.server_state msg.url

    lobby:
    send_message join_army
    send_message update_economy_modifiers
    send_message toggle_ready
    handlers.server_state meg.url; msg.state = landing

    What I've figured out so far about Gamma:

    • The VersusAI type isn't used in UI, not sure if it's illegal.
    • armies now have ai:bool and alliance:bool fields
    • The default password is undefined
    • game_config became update_game_config. The UI calls it once for each army it adds (including the first two), not sure if this is required
    • join_army commander argument becomes { ObjectName: model.preferredCommander().ObjectName }
    • toggle_ready replaced with start_game
    • game descriptions have a public field
    • the server_state message control field may be new.
    • The game starts when control.starting becomes true
    • The next screen is building_planets; haven't looked into what it does yet.
    • The server state lobby seems to correspond to new_game
    Sketch for Gamma procedure
    connect_to_game:
    engine ubernet.startGame
    engine join_game
    server_state payload.url

    new_game:
    send_message update_game_config with desc
    send_message join_army
    send_message update_economy_modifiers ????
    send_message start_game
    handlers.server_state payload.data.control.starting == true

    Keep in mind I don't have this working right now, so something is wrong.

Share This Page