README.adoc 17.6 KB
Newer Older
sirjorj's avatar
sirjorj committed
1
= xhud
sirjorj's avatar
sirjorj committed
2 3 4 5
:toc:

---

sirjorj's avatar
sirjorj committed
6 7
== Summary

sirjorj's avatar
sirjorj committed
8 9 10 11 12 13 14
xhud is a command line utility for https://fantasyflightgames.com[FFG]'s https://www.fantasyflightgames.com/en/products/x-wing/[X-Wing Miniatures Game]. It can:

* Show info for ships, pilots, upgrades
* Validate squads using the https://github.com/elistevens/xws-spec[.xws] format
* Generate an image from a squad
* Run a game of two squads, allowing the user to tweak states (shields, hull, enables, etc) for each ship to provide live stats for live streaming a game

sirjorj's avatar
sirjorj committed
15
xhud has been developed on various Unix-based systems (macOS, BSD, linux). Binary builds are available for macOS and linux (see below).  The linux builds can be run in Windows 10 using https://msdn.microsoft.com/en-us/commandline/wsl/about[Bash on Windows].  For news and updates, please follow https://twitter.com/xhudoverlay[@xhudoverlay] on twitter.
sirjorj's avatar
sirjorj committed
16 17 18 19 20 21 22 23 24 25 26 27 28 29 30

== Source

https://github.com/sirjorj/xhud[github]

xhud uses:

* http://llvm.org/[clang/llvm] to compile the code (other compilers would probably work, but I like this one)
* https://github.com/libgd/libgd[libgd] to draw the images
* https://github.com/geordanr/xwing-miniatures-font[xwing-miniatures-font] to render symbols from the game

At some point I may put instructions on how to build it here...

== Builds

31
Binaries are available http://xhud.sirjorj.com/[here].
sirjorj's avatar
sirjorj committed
32 33 34

== Installation

sirjorj's avatar
sirjorj committed
35
The downloadable builds are ready to be extracted and run.  They contain:
sirjorj's avatar
sirjorj committed
36 37

|===
sirjorj's avatar
sirjorj committed
38
|`xhud/`                                      |A folder containing everything
39
|`xhud/LICENSE`                               |Licenses for all the parts that make this work
sirjorj's avatar
sirjorj committed
40 41 42 43 44 45
|`xhud/xhud`                                  |The program itself
|`xhud/fonts/`                                |A folder for the required fonts
|`xhud/fonts/Squarish Sans CT Regular SC.ttf` |The text in the generated images
|`xhud/fonts/xwing-miniatures.ttf`            |The game sybols
|`xhud/fonts/xwing-miniatures-ships.ttf`      |The ship icons
|`xhud/fonts/xwstats.ttf`                     |The stat numbers in the generated images
sirjorj's avatar
sirjorj committed
46 47
|===

sirjorj's avatar
sirjorj committed
48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72
NOTE: older version may be a little different

=== Intro to Unix Terminal commands

If you already have experince with a unix terminal, you can skip this section.

If you are new to the scary-looking unix "command line" mode, let's run through a little primer.  NOTE: This applies to macOS Terminal, any linux terminal program you may be using, and Bash on Windows.

|===
| `cd`    | command to change the directory you are currently in
| `~`     | reference to current logged in user's home directory
| `.`     | reference to the current directory
| `..`    | reference to the parent directory
|===

NOTE: 'directory' is the proper name for 'folder'

NOTE: Another thing to remember is TAB autocomplete - when tying a command or directory or file name, if you press TAB partway through, it will autocomplete what you are typing.  If there is only one file or command that matches what you have already typed, it will finish it.  If there are more than one, hitting TAB a second time will show the possible results.  This makes using the terminal a lot faster and easier.

At this point, let's propose an organizational structure for using xhud.

* `[home folder]`
** `xwing` - folder to contain everything
*** `squads` - folder to store the .xws files
*** `xhud` - folder to store the game you downloaded and extrated from the builds page
sirjorj's avatar
sirjorj committed
73
*** `xhud_data` - folder where the generated image(s) will go
sirjorj's avatar
sirjorj committed
74

sirjorj's avatar
sirjorj committed
75
With this in place, alongside your `Documents` and `Music` and `Videos` directories, you will see an `xwing` directory.  It will contain the `xhud` directory that is extracted from the downloaded build.  This `xhud` directory will contain the items shown in the table above.  We will also add a `squads` directory to the `xwing` directory.  This is where you will put your xws files.  When `xhud` is run, it will create the overlay image `xhud.png` in the `xhud_data` directory.  This is the image you will add to your streaming software.
sirjorj's avatar
sirjorj committed
76 77 78 79 80

Ok, lets make it.

In your home directory, create a directory called `xwing`.  This can be done with macOS Finder or whatever GUI your linux distro uses or even from the terminal by typing `mkdir ~/xwing`.

sirjorj's avatar
sirjorj committed
81 82 83
Make a `squads` directory in the `xwing` directory (the command for this is `mkdir ~/xwing/squads`).  When you create a squad with whatever tool you use, you can export it as an xws file, or copy the blob of text and paste it into a new file that you name something ending with `.xws`.

Make a `xhud_data` directory in the `xwing` directory (`mkdir ~/xwing/xhud_data`).  This is where the image(s) that xhud generates will go.
sirjorj's avatar
sirjorj committed
84 85 86 87 88 89 90

Download the latest build and extract it to `xwing`.  This can be done by just double clicking on the downloaded file to extract the contents and moving the extracted `xhud` directory to the `xwing` directory we just made.

Let's make a point to not add anything to this `xhud` directory.  The reason is this: when new versions of xhud are released, you can then just delete this xhud directory and replace it with a new one from the new build you download.  If you would store your .xws squad files IN the xhud directory, it would make the update process more complicated.

With this directory structure in place, we can proceed.

sirjorj's avatar
sirjorj committed
91 92
== Usage

sirjorj's avatar
sirjorj committed
93
Open up a terminal and switch to the xhud directory (`cd ~/xwing/xhud`). You can now use xhud to do things.
sirjorj's avatar
sirjorj committed
94

sirjorj's avatar
sirjorj committed
95
NOTE: If you are using Bash on Windows, your Windows home directory will be available at `/mnt/c/Users/*username*`, so to switch to the xhud directoy, type `cd /mnt/c/Users/*username*/xhud`, where *username* is your windows username.  (When typing long directory paths like this, remember that TAB autocomplete feature I mentioned above.)
96

sirjorj's avatar
sirjorj committed
97
|===
sirjorj's avatar
sirjorj committed
98 99 100 101 102 103 104 105 106 107 108 109
|`./xhud`                                                    |Print version, usage, and options
|`./xhud check`                                              |Check to make sure the required fonts are in place
|`./xhud ship`                                               |Print a list of all the ships
|`./xhud ship awing`                                         |Print info on the A-Wing
|`./xhud pilot`                                              |Print a list of all the pilots
|`./xhud pilot lukeskywalker rebel xwing`                    |Print the info on Luke Skywalker
|`./xhud upgrade`                                            |Print a list of all the upgrades
|`./xhud upgrade mod engineupgrade`                          |Print the info on 'Engine Upgrade' Modification
|`./xhud squad ../squads/babyblues.xws`                      |Print a squad from an .xws file (this example assumes the squad file is in your xhod folder)
|`./xhud verify ../squads/babyblues.xws`                     |Verifies a squad file
|`./xhud img ../squads/babyblues.xws bb.png`                 |Generate a png image from a squad file
|`./xhud run ../squads/s1.xws ../squads/s2.xws ../xhud_data` |Run a game with the 2 specified lists, generating image(s) in a directory called xhud_data (more details below)
sirjorj's avatar
sirjorj committed
110 111 112 113 114 115
|===

Notes:

* When specifying a ship/pilot/upgrade, use the xws format of it (all lowercase, no spaces or special characters)
* When viewing ships/pilots/upgrades, shaded items are unreleased
sirjorj's avatar
sirjorj committed
116
* To print info on a ship/pilot/upgrade, you can copy the necessary input info from the list - they are ordered that way for a reason
sirjorj's avatar
sirjorj committed
117 118 119

== Running a Game

sirjorj's avatar
sirjorj committed
120
To run a game, you use xhud's 'run' command. You then specify 2 .xws files (for P1 and P2, respectively) and an image to be generated. In the examples ablve, all the squad files are in the same 'xhud' folder as the program.
sirjorj's avatar
sirjorj committed
121

sirjorj's avatar
sirjorj committed
122
Anyway, once you have this in place, open the terminal, cd to the proper folder (`cd ~/xwing/xhud`) and start a game with this:
123

sirjorj's avatar
sirjorj committed
124
 ./xhud run ../squads/babyblues.xws ../squads/palpaces.xws ../xhud_data
125

sirjorj's avatar
sirjorj committed
126
Assuming the everything was entered correctly and the squads were valid, a game will be started. In the `xhud_data` directory, you will find `xhud.png`. This is the image to add to your streaming/recording program. Make the image the full size of your streaming view so it will put the first squad you specify on the left and the second one on the right. I use OBS and when an image is overwritten, it will automatically refresh on screen, so that's all you have to do.
sirjorj's avatar
sirjorj committed
127

sirjorj's avatar
sirjorj committed
128 129
=== Commands
When the game starts, you are presented with a simple prompt. This is how you issue commands to change the game state.  The commands fall into a few basic categories:
sirjorj's avatar
sirjorj committed
130

sirjorj's avatar
sirjorj committed
131
==== Helper
sirjorj's avatar
sirjorj committed
132
These commands do things like display help, show current game state, or exit.
sirjorj's avatar
sirjorj committed
133
|===
sirjorj's avatar
sirjorj committed
134 135 136
| `?`   | Show commands
|       | Show current game state (just hit enter on an empty prompt)
| `qqq` | Quit
sirjorj's avatar
sirjorj committed
137
|===
sirjorj's avatar
sirjorj committed
138

sirjorj's avatar
sirjorj committed
139 140 141 142 143 144 145 146 147 148 149 150
==== Game Info
These command set some global information on the overlay.
|===
| `i[p]`      | Set initiative to player [p] - 1: player1, 2: player2, 0: none
|===

Examples:
|===
| `i2`                                | Player 2 has initiative
| `i0`                                | Don't show initiative
|===

sirjorj's avatar
sirjorj committed
151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185
==== Settings
These commands adjust the settings for xhud.
|===
| `settings`          | Show the settings: +
                        *Key:* one of the settings <<Keys>> (ex. `run.title`) +
                        *Def:* the default value for this key +
                        *Config:* the value currently stored in the config file +
                        *Setting:* the value currently used by xhud
| `settings {k}={v}`` | Set the key {k} to value {v} +
                        *Example:* `settings run.title=My new title` +
                        *Note:* There must not be a space between the key and the '='
| `settings write`    | Write the current settings to the config file
|===

===== Keys
[cols="2,1, 1,6", options="header"]
|===
| Setting           | Type   | Defaut | Description
| `run.autodisable` | BOOL   | no     | "yes" to autodisable the pilot when hull reaches zero
| `run.multiimage`  | BOOL   | no     | "yes" generate separate images for player1 and player2 (`p1.png` & `p2.png`) instead of `xhud.png` +
                                        *NOTE:* a ~/ prefix will NOT be resolved
| `run.outdir`      | PATH   | ""     | where xhud will put the files that it generates - can also be specified on the command line
| `run.title`       | STRING | ""     | the title to draw on the top center of the overlay
|===

Examples:
|===
| `settings`                   | See the current settings
| `settings run.title=My Game` | Set the title to `My Game`
| `settings`                   | Running this again will show the new setting in blue because it differs from the config file
| `settings write`             | Write the settings to the config file - now `My Game` will be the title when you start xhud again
|===

*Note:* when running xhud for the first time, a `settings write` will save `run.outdir` so you will no longer have to specify the output directory in future runs.

sirjorj's avatar
sirjorj committed
186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203
==== Data Lookup
These commands print game data to the console.  They do not affect the overlay.
|===
| `p [p]`         | Show stats for pilot that matches [p] - If multiple match, a list is printed
| `p [p] [f] [s]` | Show stats for pilot that matches the specified pilot/faction/ship
| `u [u]`         | Show stats for upgrade that matches [u] - If multiple match, a list is printed
| `u [t] [u]`     | Show stats for upgrade that matches the specified type/upgrade
|===

Examples:
|===
| `p soontir`                   | Show info about Soontir Fel
| `p bobafett scum firespray31` | Show info about scum Boba Fett
| `u tlt`                       | Show info about Twin Laser Turret
| `u amd r2d2`                  | Show info about astromech R2-D2 (as opposed to crew)
|===

==== Game State Manipulation
sirjorj's avatar
sirjorj committed
204
These commands are for adjusting the players' squads to reflect the game state.  They include adding or remove hull or shield, making a ship or upgrade active or inactive, adding or removing an extra munitions token, or flipping an upgrade from one side to the other.  The basic syntax of these is:
sirjorj's avatar
sirjorj committed
205

sirjorj's avatar
sirjorj committed
206 207
===== Pilot
* [PLAYER][SHIP][ACTION]
sirjorj's avatar
sirjorj committed
208

sirjorj's avatar
sirjorj committed
209
*PLAYER* - Which player's state do you want to change? (`1` or `2`)
sirjorj's avatar
sirjorj committed
210

sirjorj's avatar
sirjorj committed
211
*SHIP* - Which ship do you want to manipulate? (`1` to `number of ships`, counting down)
sirjorj's avatar
sirjorj committed
212

sirjorj's avatar
sirjorj committed
213
*ACTION* - What do you want to change? Your options are:
sirjorj's avatar
sirjorj committed
214 215

|===
sirjorj's avatar
sirjorj committed
216
|`s`	    |remove a shield     1.2+|Lower-case removes, Capital adds
sirjorj's avatar
sirjorj committed
217
|`S`	    |add a shield
sirjorj's avatar
sirjorj committed
218
|`h`	    |remove a hull       1.2+|Lower-case removes, Capital adds
sirjorj's avatar
sirjorj committed
219
|`H`	    |add a hull
sirjorj's avatar
sirjorj committed
220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245
|`a`	    |deactivate the ship 1.2+|Disable when destroyed or not yet deployed (Phantom)
|`A`	    |activate the ship
|===


===== Upgrade
* [PLAYER][SHIP][UPGRADE][ACTION]

*PLAYER* - Which player's state do you want to change? (`1` or `2`)

*SHIP* - Which ship do you want to manipulate? (`1` to `number of ships`, counting down)

*UPGRADE* - Which upgrade do you want to manipulate? (`1` to `number of upgrades`, counting left to right, top to bottom)

*ACTION* - What do you want to change? Your options are:

|===
|`a`	        |deactivate the ship   1.2+|Disable when destroyed or not yet deployed (Phantom)
|`A`	        |activate the ship
|`x`	        |remove extra token    1.2+|Add/Remove token for Extra Munitions or Jabba the Hutt's Illicit
|`X`	        |add extra token
|`f`	    1.2+|flip the card         1.2+|Flip a 2 sided card. No effect on single sided cards.
|`F`
|`(name)`  |replace upgrade with `name` *Note:* leaving `name` blank (just entering `()`) will print all possible `name` values| Vizago
|===

sirjorj's avatar
sirjorj committed
246
* Multiple actions can be issued to the same/upgrade in one command (`11ssh` will remove 2 shields and 1 hull from player 1, ship 1)
sirjorj's avatar
sirjorj committed
247
* Multiple commands, separated by commas, can be entered at one time (`11h, 12h` will remove 1 hull from player 1, ships 1 and 2)
sirjorj's avatar
sirjorj committed
248 249 250 251 252 253 254 255 256 257 258 259

Examples:

|===
|`12s`              |Player 1, Ship 2 loses a shield
|`24h`              |Player 2, Ship 4 loses a hull
|`11S`              |Player 1, Ship 1 regenerated a shield
|`21ss`             |Player 2, Ship 1 loses 2 shields
|`22shh`            |Player 2, Ship 2 loses a shield and 2 hull
|`13shha`           |Player 1, Ship 3 loses a shield, 2 hull, and is destroyed
|`211a`             |Player 2, Ship 1's 1st upgrade is deactivated (fired munition, stealth device lost, glitterstim popped, etc)
|`12A`              |Player 1, Ship 2 is deployed (ex. Phantom undocks from Ghost)
sirjorj's avatar
sirjorj committed
260
|`11s, 111a`        |Player 1, Ship 1 loses and shield and upgrade 1 is disabled (ex. Stealth Device)
sirjorj's avatar
sirjorj committed
261 262
|`231x`             |Player 2, Ship 3 fires torpedo (upgrade slot 1) and loses Extra Munitions token.
|`111f`             |Player 1, Ship 1 flips Pivot Wing (upgrade slot 1) NOTE: 111F would have the same result
sirjorj's avatar
sirjorj committed
263
|`11h,12h,13h,14h`  |Player 1, Ships 1-4 lose 1 hull (bomb detonation)
sirjorj's avatar
sirjorj committed
264 265 266
|`113(glitterstim)` |Player 1, Ship 1 replaces upgrade 3 with Glitterstim (assuming upgrade 3 is Illicit)
|===

sirjorj's avatar
sirjorj committed
267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298
==== Stat Override
These commands let you manually override the stat numbers for a ship or remove a previously set override.

* *Override:* [PLAYER][SHIP]O[STAT][VALUE]
* *Remove:* [PLAYER][SHIP]o[STAT]

*PLAYER* - Which player has a stat that you want to override? (1 or 2)

*SHIP* - Which ship has a stat that you want to override? (`1` to `number of ships`, counting down)

*O* or *o* - `O` to override a value, `o` to remove the override

*STAT* - What do you want to override?  One of the following:

|===
| `sk` | Pilot Skill
| `at` | Attack
| `ag` | Agility
| `hu` | Hull
| `sh` | Shield
|===

*VALUE* - The new value

Examples:

|===
|`11Osk0`              | Player1, Ship1 goes to pilot skill 0
|`23Osk9`              | Player2, Ship3 goes to pilot skill 9 (Thweek)
|`23osk`               | Player2, Ship3 get its pilot skill restored to its proper value
|===

sirjorj's avatar
sirjorj committed
299 300 301 302 303 304 305 306 307 308 309 310
==== Popup

These commands show temporary pop-up info such as dice results.

===== Clear

|===
| `C` or `c` | Remove all popups from view
|===

===== Dice

sirjorj's avatar
sirjorj committed
311
* [PLAYER][DICE][RESULTS]
sirjorj's avatar
sirjorj committed
312 313 314

*PLAYER* - Which player is rolling (`1` or `2`)

sirjorj's avatar
sirjorj committed
315 316
*DICE* - Which type of dice ()`A` or `a` for Attack, `D` or `d` for Defense)

sirjorj's avatar
sirjorj committed
317 318 319 320 321 322 323 324
*RESULTS* - String of dice results consisting of the following:

|===
| `C` or `c` | Critical Hit
| `H` or `h` | Hit
| `E` or `e` | Evade
| `F` or `f` | Focus
| `B` or `b` | Blank
sirjorj's avatar
sirjorj committed
325 326
|===

sirjorj's avatar
sirjorj committed
327
* There is no difference between the capital and lowercase letters in these commands
sirjorj's avatar
sirjorj committed
328 329 330 331

Examples:

|===
sirjorj's avatar
sirjorj committed
332 333
| `1Ahhc` | Player 1 rolls Attack Dice: *CRIT*, *HIT*, *HIT*
| `2Defb` | Player 2 rolls Defense Dice: *EVADE*, *FOCUS*, *BLANK*
sirjorj's avatar
sirjorj committed
334
|===
sirjorj's avatar
sirjorj committed
335 336 337 338 339 340 341 342 343

== FAQ
=== _I tried running xhud but got an 'Unknown ship' error (such as `Unknown ship (kestal/imperial/tieaggressor)`).  What does this mean?_

This means one of two thigs:

. xhud (or rather, its underlying library, libxwing) has an error
. the program that exported the squad has an error

sirjorj's avatar
sirjorj committed
344
All pilot and upgrade names have to be formatted a certain way so all the different programs can properly communicate.  The definitive guide can be found https://github.com/elistevens/xws-spec/blob/master/README_NAMES.md[here].
sirjorj's avatar
sirjorj committed
345

sirjorj's avatar
sirjorj committed
346
If the names of the pilot/faction/ship are correct (based on the guide linked above) and you still get this error, then the problem is on my end.  Please open an issue and I will get it fixed ASAP.
sirjorj's avatar
sirjorj committed
347 348 349 350

In the example above, "kestal" should be "lieutenantkestal", so the program exporting the name is wrong.  Please file a bug report to the exporting program's project so they can fix it.

In the meantime, the xws file can be opened with any text editor and the incorrect name can be changed to what xhud is looking for.
sirjorj's avatar
sirjorj committed
351 352 353 354

=== _Is there a timer?_

No.  And there probably won't be.  When xhud runs, it generates a PNG image file.  When OBS (or whatever streaming software you use) has said PNG file in the scene, it monitors it.  If the file changes, OBS reloads the image.  When you change the gamestate, xhud regenerates the image and OBS reloads it.  There is a delay.  That delay can vary from update to update.  Updating the image every second combined with the previously mentioned delay would not look good.  If you want to show a timer, use a separate program, capture the window, and add it to the scene.