Commit efc01e85 authored by Andrew's avatar Andrew

Documentation updates for Combat Encounters

parent dad46256
<p><a href="https://httpd.apache.org/" title="Apache Web Server" title="_blank">Apache</a> is a popular web server which you may consider using as a proxy server in front of Foundry Virtual Tabletop. There are a number of advantages to using a proxy server like Apache like using a subdomain, using an external port that is different than your Foundry VTT port, stronger access controls, and faster serving of static files. This article provides a basic overview of using Apache with Foundry Virtual Tabletop. There are <em>many advanced options</em> which are not covered here.</p>
<p class="note info">Please note that using a proxy server like Apache, while advantageous for dedicated web hosts, is absolutely not required in order to use Foundry Virtual Tabletop.</p>
<hr/>
<h3>Step 1 - Install Apache</h3>
<p>Start by installing Apache for your Linux distribution. Some common examples are provided below, but consult the <a href="http://httpd.apache.org/docs/2.4/install.html" title="Apache documentation" target="_blank">Apache documentation</a> for your Linux flavor.</p>
<p class="note warning">This guide assumes a basic level of familiarity with the Linux operating system and how to interface with it. If you are brand new to Linux we recommend starting with a beginner's tutorial to the Linux command line before proceeding.</p>
<h4>Ubuntu or Debian</h4>
<pre><code class="language-bash">sudo apt install apache2
</code></pre>
<h4>Red Hat or CentOS</h4>
<pre><code class="language-bash">sudo yum update -y
sudo yum -y install httpd
</code></pre>
<h4>Amazon Linux 2</h4>
<pre><code class="language-bash">sudo yum update -y
sudo yum -y install httpd
</code></pre>
<hr/>
<h3>Step 2 - Configure Apache</h3>
<p>Apache requires a configuration file which defines how the server functions. A functional starting point to begin testing Apache is the following configuration which does not use SSL certificates (we can enable those later). For the purposes of this example we assume that Foundry Virtual Tabletop is running from <code>/home/ec2-user/foundryvtt</code>, but your application installation path may be different, you should adjust the configuration file accordingly.</p>
<p class="note warning">Make sure to update the references to <code>your.hostname</code> in the configuration.</p>
<pre><code class="language-bash"># Apache .conf for reverse proxy of Foundry Virtual Tabletop.
# Requires mod_proxy mod_proxy_http mod_proxy_wstunnel for WebSocket support.
# For Ubuntu and Debian this goes in /etc/apache2/apache2.conf
# For Amazon Linux, CentOS, and RHEL this goes in /etc/httpd/conf/httpd.conf
&lt;VirtualHost *:80&gt;
ServerName your.hostname.com
# Log Configuration
ErrorLog "/var/log/httpd/your.hostname.com.error_log"
CustomLog "/var/log/httpd/your.hostname.com.access_log" common
LogLevel error
# Proxy Server Configuration
ProxyPreserveHost On
ProxyPass "/socket.io/" "ws://localhost:30000/socket.io/"
ProxyPass / http://localhost:30000/
ProxyPassReverse / http://localhost:30000/
&lt;/VirtualHost&gt;
</code></pre>
<p>Once you have configured Apache, there are some <a href="./hosting" title="Foundry VTT Options Configuration" target="_blank">configurations for Foundry Virtual Tabletop</a> you will also want to apply. Set the following options in your Foundry VTT <code>{userData}/Config/options.json</code> file which will instruct Foundry that the server is running with a proxy server in front of it on port 80.</p>
<pre><code class="language-json">"hostname": "your.hostname.com",
"routePrefix": null,
"sslCert": null,
"sslKey": null,
"port": 30000,
"proxyPort": 80
</code></pre>
<hr/>
<h3>Step 3 - Start, Stop, and Restart Apache</h3>
<p>You can use the <code>systemctl</code> utility to easily manage your Apache server.</p>
<pre><code class="language-bash"># For Ubuntu and Debian
sudo systemctl start apache2
sudo systemctl stop apache2
sudo systemctl restart apache2
# For Amazon Linux, RHEL, or CentOS
sudo systemctl start httpd
sudo systemctl stop httpd
sudo systemctl restart httpd
</code></pre>
<hr/>
<h3>Step 4 - Add SSL Certificates (Optional)</h3>
<p>For more advanced usage you can add SSL Certificates for added security. Start by creating SSL Certificates, we recommend <a href="https://certbot.eff.org/instructions" title="Certbot SSL Certificates Instructions" target="_blank">using Certbot</a>. Once your certificates are created, your Apache configuration file will be updated to use port 443 and the SSL certificates you have created.</p>
<p class="note warning">Make sure to update the references to <code>your.hostname</code> in the configuration.</p>
<pre><code class="language-bash"># Apache .conf for reverse proxy of Foundry Virtual Tabletop.
# Requires mod_proxy mod_proxy_http mod_proxy_wstunnel for WebSocket support.
# For Ubuntu and Debian this goes in /etc/apache2/apache2.conf
# For Amazon Linux, Centos, and RedHat this goes in /etc/httpd/conf/httpd.conf
&lt;VirtualHost *:443&gt;
ServerName your.hostname.com
# Log Configuration
ErrorLog "/var/log/httpd/your.hostname.com.error_log"
CustomLog "/var/log/httpd/your.hostname.com.access_log" common
LogLevel error
# SSL Configuration
SSLProxyEngine on
SSLCertificateKeyFile "/etc/letsencrypt/live/your.hostname.com/privkey.pem"
SSLCertificateFile "/etc/letsencrypt/live/your.hostname.com/fullchain.pem"
Include /etc/letsencrypt/options-ssl-apache.conf
# Proxy Server Configuration
ProxyPreserveHost On
ProxyPass "/socket.io/" "ws://localhost:30000/socket.io/"
ProxyPass / http://localhost:30000/
ProxyPassReverse / http://localhost:30000/
&lt;/VirtualHost&gt;
</code></pre>
<p>Once you have edited the Apache configuration to include your SSL certificates, be sure to do a configuration test before restarting your server. Lastly, there are some additional configuration options for Foundry Virtual Tabletop you will also want to apply. Set the following options in your Foundry VTT <code>{userData}/Config/options.json</code> file which will instruct Foundry that the server is running with a proxy server in front of it on port 443.</p>
<pre><code class="language-json">"hostname": "your.hostname.com",
"routePrefix": null,
"sslCert": null,
"sslKey": null,
"port": 30000,
"proxyPort": 443,
"proxySSL": true
</code></pre>
\ No newline at end of file
<p>Most game systems make use of situations that rely on characters taking turns, such as time-sensitive combat scenes in roleplaying games. Foundry Virtual Tabletop supports managing turn-based combat scenarios through its Combat Tracker sidebar. This article uses the word "initiative" in a general sense to represent the concept of a numeric ranking of turn order.</p>
<hr />
<h2>Combat Tracker</h2>
<p>The Combat Tracker is accessed from the second icon in the sidebar, marked as a fist. Here, encounters and their listed combatants can be viewed and managed. Like all sidebars, the Combat Tracker can be popped out into its own draggable, resizable window by right-clicking its icon at the top of the sidebar.</p>
<h3>Quick Guide to Combat Tracking</h3>
<figure>
<video width="100%" controls>
<source src="https://foundryvtt.s3-us-west-2.amazonaws.com/website-media-dev/videos/combat-tracker.webm" type="video/webm">
</video>
<figcaption>An example of adding multiple Tokens to a new Combat Encounter, rolling Initiative, and advancing the turn order.</figcaption>
</figure>
<h3>Combat Encounters, Step by Step</h3>
<p>As the Gamemaster, can follow these steps to quickly create and manage an encounter in FVTT.</p>
<ol>
<li>Navigate to the scene where the encounter takes place.</li>
<li>Select all tokens that are to be included in the encounter, through dragging a rectangle over the combatants or selecting each token with Shift + Left click. With all combatants selected, Right click one of the tokens, and click "Toggle Combat State" (the swords and shield icon) to add the selected tokens to an encounter. Additionally, players can add their own characters to the encounter by clicking this button on their tokens.</li>
<li>Roll initiative for all combatants at once using the Roll All button, or roll for just NPCs using the Roll NPCs button, allowing your players to roll initative for their own characters.</li>
<li>Roll initiative for all combatants at once using the Roll All button, or roll for just NPCs using the Roll NPCs button, allowing your players to roll initiative for their own characters.</li>
<li>With initiative rolled for all combatants, click the Begin Combat button at the bottom of the Combat Tracker to start the encounter.</li>
<li>Carry out character's turns. Players can end their own characters' turns, but NPCs must have their turn ended by a user with the Gamemaster or Assistant role. This can be done by clicking the "Next Turn" button at the bottom of the Combat Tracker.</li>
<li>When combat has concluded, end the encounter by clicking the "End Combat" button at the bottom of the Combat Tracker. This will delete the encounter and toggle the combat state of all combatants.</li>
</ol>
<hr/>
<p>[screenshot diagram for the various buttons in the Combat Tracker sidebar, as well as the "Toggle Combat State" button on tokens]</p>
<figure>
<img src="https://foundryvtt.s3.us-west-2.amazonaws.com/website-media-dev/user_1/screen/combat-tracker-buttons-2020-05-18.jpg" alt="The Combat Tracker Controls"/>
<figcaption>The Combat Tracker has a number of controls to set up and navigate the turn order.</figcaption>
</figure>
<hr/>
<h2>Encounters</h2>
<p>A fight scene, race, or any particular set of people taking turns performing actions in-game can be considered an "Encounter." An encounter is tied to a specific Scene, which is the one currently being viewed when it is created. Players will only see the encounter in the Combat Tracker if they are currently viewing that scene. When first creating a world in Foundry, there will be no encounters created. An encounter can be easily created with the Create Encounter button found at the top left of the Combat Tracker.</p>
<p>Additionally, more than one encounter can be tracked. Even an individual scene can have multiple encounters being tracked at once. Individual encounters can be added, deleted, or activated with the buttons at the top of the Combat Tracker sidebar, allowing the Gamemaster to manage multiple fights or encounters happening at once on the same scene, with their own separate turn orders. Foundry's API refers to individual encounters as a "Combat" entity.</p>
......@@ -26,5 +35,15 @@
<p>When an encounter is first created and filled with combatants, players are able to roll their own characters' initiative if desired, using the Roll Initiative button. Additionally, combatants can have their initiative roll modified at any point during combat by right-clicking the combatant in the tracker and selecting Modify. Similarly, combatants can have their initiative rerolled entirely, or the combatant can be removed from the encounter through this same right-click menu.</p>
<hr/>
<h2>Combat Tracker API</h2>
<p>Module and system developers will be pleased to know that there is a Javascript API available for those who want to use or modify the functionality present in the Combat Tracker and Encounters. See the <a title="Combat Encounter" href="/api/combat" target="_blank" rel="nofollow noopener">Combat</a> and <a title="Combat Tracker API" href="/api/combat-tracker" target="_blank" rel="nofollow noopener">Combat Tracker</a> API documentation for details.</p>
\ No newline at end of file
<h3>API References</h3>
<p>To interact with Combat Encounters programmatically, you will primarily use the following API concepts:
<ul>
<li>The <a href="/api/Combat.html" title="The Combat Entity" target="_blank">Combat</a> Entity</li>
<li>The <a href="/api/Combats.html" title="The Combats Collection" target="_blank">Combats</a> Collection</li>
<li>The <a href="/api/CombatTracker.html" title="The CombatTracker Sidebar Tab" target="_blank">CombatTracker</a> Sidebar Tab</li>
</ul>
</p>
<hr/>
<h3>Attributions</h3>
<p class="note">"Haunted Library" map and Tokens by <a href="https://www.patreon.com/forgottenadventures" title="ForgottenAdventures on Patreon" target="_blank">ForgottenAdventures on Patreon</a>.</p>
......@@ -9,12 +9,12 @@
<p class="note warning">This guide assumes a basic level of familiarity with the Linux operating system and how to interface with it. If you are brand new to Linux we recommend starting with a beginner's tutorial to the Linux command line before proceeding.</p>
<h4>Ubuntu</h4>
<h4>Ubuntu or Debian</h4>
<pre><code class="language-bash">sudo apt-get update
sudo apt-get install nginx
</code></pre>
<h4>Red Hat</h4>
<h4>Red Hat or CentOS</h4>
<pre><code class="language-bash">sudo yum update -y
sudo yum install nginx
</code></pre>
......@@ -81,6 +81,16 @@ http {
</code></pre>
<hr/>
<p>Once you have configured Nginx, there are some <a href="./hosting" title="Foundry VTT Options Configuration" target="_blank">configurations for Foundry Virtual Tabletop</a> you will also want to apply. Set the following options in your Foundry VTT <code>{userData}/Config/options.json</code> file which will instruct Foundry that the server is running with a proxy server in front of it on port 80.</p>
<pre><code class="language-json">"hostname": "your.hostname.com",
"routePrefix": null,
"sslCert": null,
"sslKey": null,
"port": 30000,
"proxyPort": 80
</code></pre>
<h3>Step 3 - Start, Stop, and Restart Nginx</h3>
<p>You can use the <code>service</code> utility to easily manage your Nginx server.</p>
......@@ -99,7 +109,7 @@ sudo service nginx restart
<hr/>
<h3>Step 4 - Add SSL Certificates (Optional)</h3>
<p>For more advanced usage you can add SSL Certificates for added security. Start by creating SSL Certificates (not covered by this guide). Once your certificates are created, your Nginx configuration file will be updated to use port 443 and the SSL certificates you have created.</p>
<p>For more advanced usage you can add SSL Certificates for added security. Start by creating SSL Certificates, we recommend <a href="https://certbot.eff.org/instructions" title="Certbot SSL Certificates Instructions" target="_blank">using Certbot</a>. Once your certificates are created, your Nginx configuration file will be updated to use port 443 and the SSL certificates you have created.</p>
<p class="note warning">Make sure to update the references to <code>your.hostname</code> in the configuration.</p>
......@@ -155,4 +165,13 @@ http {
}
</code></pre>
<p>Once you have edited the Nginx configuration to include your SSL certificates, be sure to do a configuration test before restarting your server.</p>
\ No newline at end of file
<p>Once you have edited the Nginx configuration to include your SSL certificates, be sure to do a configuration test before restarting your server. Lastly, there are some additional configuration options for Foundry Virtual Tabletop you will also want to apply. Set the following options in your Foundry VTT <code>{userData}/Config/options.json</code> file which will instruct Foundry that the server is running with a proxy server in front of it on port 443.</p>
<pre><code class="language-json">"hostname": "your.hostname.com",
"routePrefix": null,
"sslCert": null,
"sslKey": null,
"port": 30000,
"proxyPort": 443,
"proxySSL": true
</code></pre>
\ No newline at end of file
......@@ -6,12 +6,13 @@
<p>This is the situation which occurs with web traffic. External requests know the public IP address of your local network (think of this as the "street address" of the building), but they don't know your local IP address within that network (think of this as your "apartment number" within the building).</p>
<p>What port forwarding does is it helps to correctly route incoming traffic which arrives on a certain port to the correct internal IP address on the network which is expecting to recieve it. You are "forwarding" your traffic the same way you might forward physical mail. For the Foundry Virtual Tabletop use case, when traffic arrives at your external IP address on port <code>30000</code> (or an alternative port you choose to use), the port forwarding rule will automatically direct that traffic to your local PC which is running the Foundry application.</p>
<h2>When is Port Forwarding Not Required?</h2>
<h4>When is Port Forwarding Not Required?</h4>
<p>Under some circumstances, port forwarding may not be required:</p>
<ul>
<li>If you have an <a title="About IPv6" href="https://en.wikipedia.org/wiki/IPv6" target="_blank" rel="nofollow noopener">IPv6 address</a> you <em>probably</em> do not need to port forward. IPv6 is an expanded protocol which is able to refer to specific device IPs.</li>
<li>If you are using a router which supports <a title="About UPnP" href="https://en.wikipedia.org/wiki/Universal_Plug_and_Play" target="_blank" rel="nofollow noopener">Universal Plug and Play (UPnP)</a> and has that feature enabled you <em>probably</em> do not need to port forward.</li>
</ul>
<hr/>
<h2>How do I Port Forward?</h2>
<p>The exact steps necessary in order to port forward vary depending on you router and the interface it provides, but at a high level process is the same in all cases. Some screenshots are provided for assistance with Windows use cases, although the process uses similar concepts for MacOS or Linux.</p>
......@@ -28,6 +29,7 @@
<figure><img src="https://foundryvtt.s3.us-west-2.amazonaws.com/website-media-dev/user_1/asset/port-forwarding-example-2020-03-20.png" alt="Port Forwarding Example" width="576" height="652" />
<figcaption>An example of port forwarding for a specific router model. My local IP address is 192.168.1.100.</figcaption>
</figure>
<hr/>
<h2>Frequently Asked Questions</h2>
<blockquote class="question">
......
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