User Interface Modding

From Camelot Unchained Wiki
Jump to: navigation, search

The user interface is built out of the web. What does this "out of the web" mean? Our UI is built on top of Chromium Embedded Framework (CEF), which is based on a fork of Chromium, the same code on which the Google Chrome web browser is built. Each UI widget is effectively a web page, or more accurately a chromium window that runs inside the client, that communicates with the game via a client JavaScript API (cuAPI) and the game server via a REST Web Service API (CU REST API). Using this technology UI developers only require knowledge of common web technologies.

Disclaimer: This is pre-release (alpha) software and all information about UI modding is subject to change throughout the development process.

Skills[edit | edit source]

The skills required for UI development are listed below, split into basic UI development (the minimal required knowledge to be able to write UIs in Camelot Unchained) and advanced UI development.

Basic UI development[edit | edit source]

  • HTML
  • JavaScript

Advanced UI development[edit | edit source]

  • HTML5 (CSS, DOM, HTML5 APIs)
  • TypeScript (optional: We develop our UI widgets with TypeScript, you can use plain JS or any other compiled version of JS you prefer)
  • jQuery (optional: We use jQuery, but you don't have to in your own addons / mods)
  • any other framework you wish to include, if it works in Chrome it will likely work in our UI! (With a few exceptions such as OpenGL support is limited in our current version of CEF)

A UI developer can certainly get by with just the basic skills of HTML and JavaScript. All UI developers will need to learn at least parts of the cuAPI interface, as this is how UI widgets communicates with the game.

Getting Started[edit | edit source]

assets\webui[edit | edit source]

The UI files are stored underneath the game bin directory [game-dir]\bin\[n]\client\assets\webui where [game-dir] is where Camelot Unchained is installed and [n] is the version of the client (where multiple versions are installed). This folder contains all the standard UIs and any custom UIs (subject to change) that are installed.

Client Version Numbers:

  • Hatchery : 4
  • Wrymling : 10

Note: for now standard UIs are overwritten each time the client is run unless they are marked as read-only

.ui files[edit | edit source]

Each UI starts with a .ui file. A .ui file is a JSON format file that contains basic details of the UI necessary for the client to be able to launch it. Here is an example from the mehuge-bct UI (basic combat text):-

 {
   "_LICENSE" : "This Source Code Form is subject to the terms of the Mozilla Public License...blah blah",
   "name" : "mehuge-bct" ,
   "mainFile" : "mehuge-bct/bct.html" ,
   "rect" : {
       "left" : 571 ,
       "top" : 280 ,
       "right" : 860 ,
       "bottom" : 350
   },
   "handlesEnemyTarget" : true ,
   "handlesFriendlyTarget" : true ,
   "handlesCharacter" : true
 }
"_LICENSE"
License String
"name"
The name of the UI. This should match the name of the .ui file (in this example, mehuge-bct). When a UI is loaded by the game, it uses the name passed to cuAPI.OpenUI to locate its .ui file. However, when a name is passed to cuAPI.CloseUI it finds and closes the UI based on the "name": entry. Having these different would cause no end of confusion.
"mainFile"
This is the initial HTML file to load. Essentially the bootstrap file. By convention, this is generally located in a sub-folder of the same name as the "name" field but doesn't have to be.
"rect"
Defines the co-ordinates for the rectangle the UI will occupy inside the client, on a 1440,900 grid. This is then scaled to the whatever the current client resolution is.
"handles*"
These are a set of flags / requests for access to different parts of the cuAPI.

Basic UI filesystem structure[edit | edit source]

This is by no means the definitive structure, more complex UIs may have a more complex structure, but for building a basic UI this is a good starting point.

myui.ui
myui\myui.html
myui\myui.css
myui\myui.js (or .ts if using typescript)

Common Files[edit | edit source]

The vendor folder contains 3rd party resources. The images folder contains all the stock images that are used by the default UI and can also be used by custom UIs. Under normal circumstances it would not be appropriate to store custom UI images in this folder.

Development Environment[edit | edit source]

To build the official CU UI visit our GitHub CU-UI project for details.