Commit 70d71e07 authored by sirjorj's avatar sirjorj

new README

parent 17c37f25
= xhud
:toc:
---
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
xhud has been developed on various Unix-based systems (macOS, BSD, linux). If you know enough to want to run it on linux, you can probably just build it yourself. To run it on macOS, use the latest build from below.
I wanted to have a Windows build as well, but it turns out that Windows is a garbage OS that does not support sane build environments. After blowing a few days trying to get anything to build (Windows has no stdio.h!), I decided to stop wasting my time on this crappy platform. While I have gotten it to work in that Ubuntu/bash feature in Windows 10, it is kind of a pain to do so. The best bet is to use linux in a virtual machine and have xhud generate the images in a shared folder. I have done with with VirtualBox as the VM and OBS as the streaming program and it worked just fine. I may document this at some point.
== 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
Binaries are available http://sirjorj.com/jorj/xhud.html[here].
== Installation
Download the latest build and extract it in your home directory. The build files (after v0.1) contain the following:
|===
|`xhud/` |A folder containing everything
|`xhud/xhud` |The program itself
|`xhud/fonts/` |A folder for the required fonts
|`xhud/fonts/README` |A text file explaining what other fonts are required
|`xhud/fonts/xwing-miniatures.ttf` |The font containing all the game sybols
|`xhud/fonts/xwing-miniatures-ships.ttf` |The font containing all the ship icons
|===
Read the README file. It will direct you on how to get the other fonts. Put them in the fonts directory with the two xwing-miniatures-* fonts. You should then be ready to go.
== Usage
Open up a terminal and switch to the xhud directory (cd xhud). You can now use xhud to do things.
|===
|`./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 babyblues.xws` |Print a squad from an .xws file (this example assumes the squad file is in your xhod folder)
|`./xhud verify babyblues.xws` |Verifies a squad file
|`./xhud img babyblues.xws bb.png` |Generate a png image from a squad file
|`./xhud run s1.xws s2.xws out` |Run a game with the 2 specified lists and put the images in a folder called 'out' (more details below)
|===
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
* 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
== Running a Game
To run a game, you use xhud's 'run' command. You then specify 2 .xws files (for P1 and P2, respectively) and a folder where the generated images will go. In the examples ablve, all the squad files are in the same 'xhud' folder as the program. For organizational purposes, you will probably have a 'squads' folder alongside the 'xhud' folder. For the output folder, lets say you also have an 'xhud_out' folder alongside 'xhud' and 'squads', like this:
* `[home folder]`
** `squads` - .xws files are stored here
** `xhud` - the contents of the xhud build you downloaded from here, plus the added fonts
** `xhud_out` - this is where the generated images will go
Or you could put these 3 folders in an 'xwing' folder for even better containment. Then, you would open terminal and type cd xwing/xhud to do the above examples.
Anyway, once you have this in place, open the terminal, cd to the proper folder and start a game with this:
./xhud run ../squads/babyblues.xws ../squads/palpaces.xws ../xhud_out
Assuming the everything was entered correctly and the squads were valid, a game will be started. In the xhud_out directory, you will find p1.png and p2.png. These are the images to add to your streaming/recording program. I use OBS and put p1.png on the left and p2.png on the right. With OBS, when an image is overwritten, it will automatically refresh on screen, so that's all you have to do.
When the game starts, you are presented with a simple prompt. This is how you issue commands to change the game state. A '?' command will show you a list of options, and a 'qqq' command will exit the game. To change game state, you tell it what to do by passing in command codes. The basic syntax of these is:
* [PLAYER][SHIP][COMMAND]
* [PLAYER][SHIP][UPGRADE][COMMAND]
*PLAYER* - Which player's state do you want to change?
*SHIP* - Which ship do you want to change? The top one is '1', and they count down from there.
*UPGRADE* - Which upgrade do you want to change? Since they are displayed in 2 columns, they are numbered like this:
|===
|1 |2
|3 |4
|5 |6
|===
*COMMAND* - What do you want to change? Your options are:
|===
|`s` |remove a shield 1.2+|Lower-case removes, Capital adds
|`S` |add a shield
|`h` |remove a hull 1.2+|Lower-case removes, Capital adds
|`H` |add a hull
|`e` |disable the ship 1.2+|Disable when destroyed or not yet deployed (Phantom)
|`E` |enable 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` |
|===
* Multiple commands can be issued to the same/upgrade in one command
* Multiple commands, separated by spaces, can be entered at one time
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, Ship 2 loses a shield and 2 hull
|`13shhe` |Player 1, Ship 3 loses a shield, 2 hull, and is desctoyed
|`211e` |Player 2, Ship 1's 1st upgrade is disabled (fired munition, stealth device lost, glitterstim popped, etc)
|`12E` |Player 1, Ship 2 is deployed (ex. Phantom undocks from Ghost)
|`11s 111e` |Player 1, Ship 1 loses and shield and upgrade 1 is disabled (ex. Stealth Device)
|`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
|`11h 12h 13h 14h` |Player 1, Ships 1-4 lose 1 hull (bomb detonation)
|===
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment