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

---

sirjorj's avatar
sirjorj committed
6 7
== Summary

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

* 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

15
xhud1e 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, check out http://xhud.sirjorj.com.
sirjorj's avatar
sirjorj committed
16 17 18

== Source

19
https://gitlab.com/sirjorj/xhud1e[gitlab]
sirjorj's avatar
sirjorj committed
20

21
xhud1e uses:
sirjorj's avatar
sirjorj committed
22 23 24 25 26 27 28

* 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

== Builds

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

== Installation

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

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

sirjorj's avatar
sirjorj committed
46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64
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.

65
At this point, let's propose an organizational structure for using xhud1e.
sirjorj's avatar
sirjorj committed
66 67 68 69

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

73
With this in place, alongside your `Documents` and `Music` and `Videos` directories, you will see an `xwing` directory.  It will contain the `xhud1e` directory that is extracted from the downloaded build.  This `xhud1e` 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 `xhud1e` is run, it will create the overlay image `xhud.png` in the `xhud1e_data` directory.  This is the image you will add to your streaming software.
sirjorj's avatar
sirjorj committed
74 75 76 77 78

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
79 80
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`.

81
Make a `xhud1e_data` directory in the `xwing` directory (`mkdir ~/xwing/xhud1e_data`).  This is where the image(s) that xhud1e generates will go.
sirjorj's avatar
sirjorj committed
82

83
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 `xhud1e` directory to the `xwing` directory we just made.
sirjorj's avatar
sirjorj committed
84

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

With this directory structure in place, we can proceed.

sirjorj's avatar
sirjorj committed
89 90
== Usage

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

93
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 xhud1e directoy, type `cd /mnt/c/Users/*username*/xhud1e`, where *username* is your windows username.  (When typing long directory paths like this, remember that TAB autocomplete feature I mentioned above.)
94

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

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
114
* 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
115 116 117

== Running a Game

118
To run a game, you use xhud1e'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 'xhud1e' folder as the program.
sirjorj's avatar
sirjorj committed
119

120
Anyway, once you have this in place, open the terminal, cd to the proper folder (`cd ~/xwing/xhud1e`) and start a game with this:
121

122
 ./xhud1e run ../squads/babyblues.xws ../squads/palpaces.xws ../xhud1e_data
123

124
Assuming the everything was entered correctly and the squads were valid, a game will be started. In the `xhud1e_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
125

sirjorj's avatar
sirjorj committed
126 127
=== 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
128

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

sirjorj's avatar
sirjorj committed
137 138 139 140 141 142 143 144 145 146 147 148
==== 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
149
==== Settings
150
These commands adjust the settings for xhud1e.
sirjorj's avatar
sirjorj committed
151 152 153 154 155
|===
| `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 +
156
                        *Setting:* the value currently used by xhud1e
sirjorj's avatar
sirjorj committed
157 158 159 160 161 162 163 164 165 166 167 168 169
| `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
170
| `run.outdir`      | PATH   | ""     | where xhud1e will put the files that it generates - can also be specified on the command line
sirjorj's avatar
sirjorj committed
171 172 173 174 175 176 177 178
| `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
179
| `settings write`             | Write the settings to the config file - now `My Game` will be the title when you start xhud1e again
sirjorj's avatar
sirjorj committed
180 181
|===

182
*Note:* when running xhud1e 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
183

sirjorj's avatar
sirjorj committed
184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201
==== 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
202
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
203

sirjorj's avatar
sirjorj committed
204 205
===== Pilot
* [PLAYER][SHIP][ACTION]
sirjorj's avatar
sirjorj committed
206

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

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

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

|===
sirjorj's avatar
sirjorj committed
214
|`s`	    |remove a shield     1.2+|Lower-case removes, Capital adds
sirjorj's avatar
sirjorj committed
215
|`S`	    |add a shield
sirjorj's avatar
sirjorj committed
216
|`h`	    |remove a hull       1.2+|Lower-case removes, Capital adds
sirjorj's avatar
sirjorj committed
217
|`H`	    |add a hull
sirjorj's avatar
sirjorj committed
218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243
|`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
244
* 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
245
* 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
246 247 248 249 250 251 252 253 254 255 256 257

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
258
|`11s, 111a`        |Player 1, Ship 1 loses and shield and upgrade 1 is disabled (ex. Stealth Device)
sirjorj's avatar
sirjorj committed
259 260
|`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
261
|`11h,12h,13h,14h`  |Player 1, Ships 1-4 lose 1 hull (bomb detonation)
sirjorj's avatar
sirjorj committed
262 263 264
|`113(glitterstim)` |Player 1, Ship 1 replaces upgrade 3 with Glitterstim (assuming upgrade 3 is Illicit)
|===

sirjorj's avatar
sirjorj committed
265 266 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
==== 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
297 298 299 300 301 302 303 304 305 306 307 308
==== 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
309
* [PLAYER][DICE][RESULTS]
sirjorj's avatar
sirjorj committed
310 311 312

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

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

sirjorj's avatar
sirjorj committed
315 316 317 318 319 320 321 322
*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
323 324
|===

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

Examples:

|===
sirjorj's avatar
sirjorj committed
330 331
| `1Ahhc` | Player 1 rolls Attack Dice: *CRIT*, *HIT*, *HIT*
| `2Defb` | Player 2 rolls Defense Dice: *EVADE*, *FOCUS*, *BLANK*
sirjorj's avatar
sirjorj committed
332
|===
sirjorj's avatar
sirjorj committed
333 334

== FAQ
335
=== _I tried running xhud1e but got an 'Unknown ship' error (such as `Unknown ship (kestal/imperial/tieaggressor)`).  What does this mean?_
sirjorj's avatar
sirjorj committed
336 337 338

This means one of two thigs:

339
. xhud1e (or rather, its underlying library, libxwing) has an error
sirjorj's avatar
sirjorj committed
340 341
. the program that exported the squad has an error

sirjorj's avatar
sirjorj committed
342
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
343

sirjorj's avatar
sirjorj committed
344
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
345 346 347

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.

348
In the meantime, the xws file can be opened with any text editor and the incorrect name can be changed to what xhud1e is looking for.
sirjorj's avatar
sirjorj committed
349 350 351

=== _Is there a timer?_

352
No.  And there probably won't be.  When xhud1e 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, xhud1e 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.