API Guide for UI Modding

Discussion in 'Mod Discussions' started by ORFJackal, December 16, 2013.

  1. ORFJackal

    ORFJackal Active Member

    Messages:
    287
    Likes Received:
    248
    I wrote this document as an aid for developers who want to get into modding PA, without having to dig through all the code. I've only spent one evening exploring the UI code before writing this document, so please correct any mistakes.

    Since the APIs will evolve a lot before the game is released, this document does not attempt to document the API in detail. Instead it will tell you to RTFS while giving some pointers that where to look.

    Last updated for version 58197.

    Architecture

    PA's UI is made out of HTML, CSS and JavaScript. If you're familiar with developing web applications, then developing PA mods should be quite familiar. To debug the game, go to the PA installation directory and start the "Coherent\Debugger\Win64\Debugger.exe" program while PA is running. It gives you access to what's similar to Chrome's Developer Tools:

    [​IMG]

    The game's core is implemented using C++ and the JavaScript-based UI communicates with it using Coherent UI. The global engine object handles all the low-level communication between UI and the game engine. Look for "engine." in all .js files under "media\ui" to see what operations are available. There are lots of engine.call/asyncCall method calls which send events to the game engine, and there are a couple of engine.on calls (in "media\ui\alpha\shared\js\common.js") that setup callbacks for receiving events from the game engine.

    Insted of having to use use the engine object directly, there are wrapper methods for most of the operations. Events from the engine are handled using the methods in the handlers and globalHandlers objects. Methods for sending events to the engine are mostly in the api object (created by "media\ui\alpha\shared\js\api\*.js"). Use the debugger's console to inspect what methods those objects have (i.e. type the object's name into the console and press Enter). Inspect the window object to see all global objects (it'll probably be messy - also all globals from mods are there and I sense much sloppiness in namespace usage).

    Pages

    The UI is made out of multiple HTML pages. For example the view when a game is running is defined in "media\ui\alpha\live_game\live_game.html" and the accompanied CSS and JavaScript files, as referenced in the HTML's script tags. The "media\ui\alpha\live_game\live_game.js" file is especially of interest, because it creates the global model object which contains pretty much everything that the UI elements show or do. It also registers lots of handlers that update the model. I recommend reading through the live_game.js file.

    If you change any of the files, you can press F5 in the debugger or game to reload the page to see your changes (just as in web development).

    The UI pages use the Knockout library for updating the view when the underlying model changes; see the data-bind attributes in the HTML elements and the calls to the ko.observable and ko.computed methods in the JavaScript.

    I recommend reading the source of the game's pages and other mods to learn how to create your own mods.

    Holodeck (Can't Touch This)

    The live_game.html contains a DIV element called holodeck into which a 3D view of the game is rendered (probably using some Coherent magic). Those 3D things cannot be accessed nor changed directly using JavaScript. There is also a model.holodeck object (defined in "media\ui\alpha\shared\js\api\holodeck.js" and instantiated in live_game.js) which handles mouse input to the game. The holodeck and the keyboard commands seen in "media\ui\alpha\shared\js\inputmap.js" are currently the only ways to control the game world - UI mods cannot do things that are not possible to do with keyboard and mouse.

    Maybe this limitation is to prevent cheating (e.g. by creating an AI that controls your units - if that is considered cheating), or then Uber just hasn't yet gotten to improving the API. Also only a limited amount of information about the units is exposed to the UI - the minimum amount to implement the current UI elements - but at least the developers have said that later they would expose more data to the UI.
    Last edited: December 17, 2013
    Quitch, trialq, cwarner7264 and 4 others like this.
  2. ORFJackal

    ORFJackal Active Member

    Messages:
    287
    Likes Received:
    248
  3. LavaSnake

    LavaSnake Post Master General

    Messages:
    1,620
    Likes Received:
    691
    Wow, great guide. I've written a few PA mods before and I still found the info to be quite helpful.
  4. Raevn

    Raevn Moderator Alumni

    Messages:
    4,226
    Likes Received:
    4,324
  5. proeleert

    proeleert Post Master General

    Messages:
    1,681
    Likes Received:
    1,656
    Nice, will help new people a lot !
  6. swizzlewizzle

    swizzlewizzle Active Member

    Messages:
    216
    Likes Received:
    56
    I hope i'm never going to have to do any UI modding, but anyways, THANK YOU ORF Jackal for this short API Guide. Seriously, the most difficult thing about modding isn't the actual coding, it's wadding through the code trying to understand things that could have been explained through a few short tutorials/guides. I mean, I know "discovery" of the code and all that is good for the soul and for becoming a better developer, but sometimes I just want to get right into the meat of the coding I want to do. You know what I mean? :)
  7. chrisjshull

    chrisjshull Member

    Messages:
    68
    Likes Received:
    38
    The Debugger for Mac crashes for me. Do we need a new build?
  8. wondible

    wondible Post Master General

    Messages:
    3,299
    Likes Received:
    2,089
    You can also point a browser at http://127.0.0.1:9999 I've used Chrome, which is the same webkit as the game; I just tried it with Firefox which didn't go so well.
  9. chrisjshull

    chrisjshull Member

    Messages:
    68
    Likes Received:
    38
    Hmm, I get a list of "Inspectable pages" - but all the links lead to blank pages.
  10. wondible

    wondible Post Master General

    Messages:
    3,299
    Likes Received:
    2,089
    The first page is often pretty boring. The main view is usually 3/4. At least with Google Chrome on OS X, and the Coherent Debugger. Do you have an anti-virus or firewall that might be getting in the way?

    Also, sometimes the UberLauncher doesn't quite close, and it ends up on the debugger address.
  11. wondible

    wondible Post Master General

    Messages:
    3,299
    Likes Received:
    2,089
    Okay, now I'm getting this with 62857.
  12. wondible

    wondible Post Master General

    Messages:
    3,299
    Likes Received:
    2,089

Share This Page