Commit cffc04a4 authored by Andrew's avatar Andrew Committed by acclayto

Add documentation page for AV feature

parent 555b81ba
_static/images/player-config.jpg

102 KB | W: | H:

_static/images/player-config.jpg

50.2 KB | W: | H:

_static/images/player-config.jpg
_static/images/player-config.jpg
_static/images/player-config.jpg
_static/images/player-config.jpg
  • 2-up
  • Swipe
  • Onion skin
......@@ -24,10 +24,10 @@ copyright = '2019, Foundry Gaming LLC'
author = 'Andrew Clayton'
# The short X.Y version
version = '0.3.7'
version = '0.4.2'
# The full version, including alpha/beta/rc tags
release = 'Beta 0.3.7'
release = 'Beta 0.4.2'
# -- General configuration ---------------------------------------------------
......
......@@ -25,6 +25,7 @@ roleplaying games in a beautiful and intuitive web-based application.
pages/glossary
pages/entities
pages/dice
pages/features/av
pages/api
pages/systems
pages/modules
......
<h2>Beta 0.4.2 Update Notes</h2>
<p>Greetings ...</p>
<p>The focus of this update is ...</p>
<p>Thank you all for appreciating my work, providing thoughtful feedback, and encouraging me to do even more. As always, please keep an eye on the development progress board here for visibility into what features are in progress and coming up next!</p>
<p><a href="https://gitlab.com/foundrynet/foundryvtt/boards" target="_blank" title="FVTT Story Board">https://gitlab.com/foundrynet/foundryvtt/boards</a></p>
<hr/>
<h3>New Features</h3>
<ul>
<li></li>
</ul>
<hr/>
<h3>Core Bug Fixes</h3>
<ul>
<li></li>
</ul>
<hr/>
<h3>Core Software, APIs, and Module Development</h3>
<ul>
<li></li>
</ul>
<hr/>
<h3>Documentation Improvements</h3>
<ul>
<li>Added overview page for the User entity:</li>
<li>Expanded the detail provided on the API documentation for the User entity: </li>
<li>Added an overview page for the Item entity type: pages/entities/item.html</li>
<li>Added instructions page for Audio/Video Communication features:</li>
</ul>
<hr/>
<h2>Beta 0.x.x Update Notes</h2>
<h2>Beta 0.4.2 Update Notes</h2>
<p>Greetings...</p>
<p>Greetings ...</p>
<p>Description...</p>
<p>The focus of this update is ...</p>
<p>Thank you all for appreciating my work, providing thoughtful feedback, and encouraging me to do even more. As always, please keep an eye on the development progress board here for visibility into what features are in progress and coming up next!</p>
......@@ -27,7 +27,7 @@
</ul>
<hr/>
<h3>D&D5e System Improvements</h3>
<h3>Documentation Improvements</h3>
<ul>
<li></li>
</ul>
......
......@@ -35,3 +35,4 @@ This page contains an archive of published update notes dating back to late stag
notes-0.3.8
notes-0.3.9
notes-0.4.0
notes-0.4.1
......@@ -12,7 +12,24 @@ When viewing or interacting with an actor inside the tabletop framework, the act
the :class:`ActorSheet` class (by default). Game systems which want to fine-tune how the actor data is rendered may
override this to a subclass included in their own definition.
----
.. contents:: Actors API Components
:depth: 1
:local:
:backlinks: top
------
The Actor Class
===============
.. autoclass:: foundry.Actor
:members:
.. autofunction:: Entity.create
.. autofunction:: Entity#update
.. autofunction:: Entity#delete
------
The Actors Collection
=====================
......@@ -26,23 +43,10 @@ The Actors Collection
.. autofunction:: Collection#index
.. autofunction:: Collection#render
----
The Actor Class
===============
.. autoclass:: foundry.Actor
:members:
.. autofunction:: Entity.create
.. autofunction:: Entity#update
.. autofunction:: Entity#delete
----
------
The Actor Sheet
===============
.. autoclass:: ActorSheet
:members:
......@@ -24,6 +24,23 @@ When viewing or interacting with an item's data, the item is rendered and edited
which can be extended or overridden by systems or modules. To override the default implementation, a mod should
define the ``CONFIG.Item.sheetClass`` global configuration value.
.. contents:: Items API Components
:depth: 1
:local:
:backlinks: top
----
The Item Class
==============
.. autoclass:: foundry.Item
:members:
.. autofunction:: Entity.create
.. autofunction:: Entity#update
.. autofunction:: Entity#delete
----
The Items Collection
......@@ -40,18 +57,6 @@ The Items Collection
----
The Item Class
==============
.. autoclass:: foundry.Item
:members:
.. autofunction:: Entity.create
.. autofunction:: Entity#update
.. autofunction:: Entity#delete
----
The Item Sheet
==============
......
......@@ -17,6 +17,23 @@ Additionally, each scene has rich notes associated with it which are customizabl
class. Similarly, this class can be overridden or extended by modules by altering the ``Config.Scene.notesClass``
global configuration.
.. contents:: Scenes API Components
:depth: 1
:local:
:backlinks: top
----
The Scene Class
===============
.. autoclass:: foundry.Scene
:members:
.. autofunction:: Entity.create
.. autofunction:: Entity#update
.. autofunction:: Entity#delete
----
The Scenes Collection
......@@ -33,20 +50,16 @@ The Scenes Collection
----
The Scene Class
===============
Scene Configuration Sheet
=========================
.. autoclass:: foundry.Scene
.. autoclass:: SceneSheet
:members:
.. autofunction:: Entity.create
.. autofunction:: Entity#update
.. autofunction:: Entity#delete
----
The Scene Sheet
===============
Scene Notes
===========
.. autoclass:: SceneSheet
.. autoclass:: SceneNotes
:members:
......@@ -3,11 +3,26 @@
The User Entity
***************
Each connected client corresponds to a :class:`User` instance. Control of Actors and other permissions are configured
at the User level, so having different users allows you to give players access to different content. Each user is
assigned a permission level which controls what capabilities they will have within the Virtual Tabletop.
Each connected client corresponds to an instance of the :class:`User` Entity. The collection of all such Entities is stored in the :class:`Users` Collection. Refer to the :ref:`users` page for documentation regarding the User concept and its usage within Foundry VTT.
----
.. contents:: Users API Components
:depth: 1
:local:
:backlinks: top
------
The User Instance
=================
.. autoclass:: User
:members:
.. autofunction:: Entity.create
.. autofunction:: Entity#update
.. autofunction:: Entity#delete
------
The Users Collection
====================
......@@ -19,14 +34,10 @@ The Users Collection
.. autofunction:: Collection#remove
.. autofunction:: Collection#get
----
The User Instance
=================
------
.. autoclass:: User
:members:
The Player Config Application
=============================
.. autofunction:: Entity.create
.. autofunction:: Entity#update
.. autofunction:: Entity#delete
.. autoclass:: PlayerConfig
:members:
......@@ -5,12 +5,13 @@ The term Entities is used to describe the individual records of data which compr
and more which are featured within the World. This chapter introduces you to the different Entity types which are
used within Foundry Virtual Tabletop and the API layers which allow you to modify them.
.. toctree::
:caption: Entity Types
:name: entities
:maxdepth: 1
entities/user
entities/scene
entities/actor
entities/item
entities/compendium
.. _item:
The Item Entity
***************
A key Entity within Foundry Virtual Tabletop is the Item. Each Item represents a physical or conceptual component
which can be "owned" by an Actor. Items could range from something very tangible like a Longsword which is carried
in the Actor's inventory to something more philosophical like a Background, Feat, or Trait which grants the Actor
which owns it additional abilities or bonuses.
Since Foundry Virtual Tabletop is designed to be system agnostic, it is very difficult to anticipate what exact
types of "Items" will be required by different game systems to enable their game mechanics and character progression.
It is therefore left up to System developers to define the types of Items which are relevant for the needs of the
system and the data structures that each Item type contains.
Most Items start as globally defined as Entities within the World, but once an Item is added to an Actor, it becomes
an Owned Item which no longer has a global ID, but rather a local ID within the parent Actor's set of items.
.. contents:: Working with Items
:depth: 1
:local:
:backlinks: top
-----
Item Creation and Configuration
===============================
To create a new Item, navigate to the Items Directory in the sidebar by clicking on the icon that looks like a suitcase.
At the bottom of this directory tab you can create a new Item, or create Folder structures to organize your collection of
Item entitites.
Configuration of Items is controlled by the Game System implementation, as the types of Items and their data structures
are an integral part of the system itself. Generally speaking, an Item is configured using an Item Sheet, which may vary
in form and function for different types of Items. Specialty Item Sheets can also be added by modules which can extend or
replace the default sheets which come with a certain game system.
.. figure:: /_static/images/item-sheet-5e.jpg
An example of the Item Sheet from the D&D5E system for the Spell type Item.
-----
Item Permissions
================
Each Item can have permissions configured at an individual User level. The level of permission given to an Item affect
which Users are able to see an interact with it inside the World sidebar directory. To modify the configured permissions
for an Item, right click on it's entry in the sidebar and select the Permissions config. The chosen **Default** permission
level for the Item applies to all users unless they are a Game Master (who can access all Items) or that specific User
is granted a different permission level.
None
The User is not able to see the Item in the sidebar or interact with it's Item Sheet. This is the initial default
permission level for new Items.
Limited
The User is able to see the Item entry in the sidebar, and observe limited (but not full) details regarding that
Item. The amount of detail provided to users with a Limited permission level is a choice left up to the game system
or Item Sheet module developer.
Observer
The User is able to see the Item entry in the sidebar directory and inspect it's Item Sheet, but is not able to
edit or otherwise make changes to the Item.
Owner
The User has full control over the Item, can see it in the sidebar, can open it's Item Sheet, and can make changes
to the Item's data. Note that only Game Master users can edit Item permissions.
-----
The Item Entity API
===================
For module developers interested in working with Items, API documentation for this Entity type is described on the
:ref:`itemAPI` page.
\ No newline at end of file
.. _user:
The User Entity
***************
Each player who connects to a Foundry Virtual Tabletop session is a User. Users represent human beigns (or possibly programmatic players) and are the cornerstone of identity in FVTT.
.. contents:: Users Overview
:depth: 1
:local:
:backlinks: top
User Creation and Configuration
===============================
Users are created within an active World, and the set of Users is specific to that world. There are no global user accounts, each World maintains it's own player list and user-level permission controls.
To create a new User, visit the **Configure Players** screen through the Escape Menu or on the Settings Sidebar while logged into the World as a GameMaster user. From this management panel you can create new users, delete existing users, or change a user's name, access key, or role.
.. figure:: /_static/images/players-config.jpg
The Players Configuration screen allows you to modify the Users who can participate in your Foundry VTT World.
User Config Settings
====================
Within the application, there are additional configuration options for each User which can be customized by either a GameMaster user or by the player themselves by right-clicking on the **Players HUD** at the bottom-left corner of the UI.
.. figure:: /_static/images/player-config.jpg
The config sheet for a single User allows that player to choose their preferred character and other User-specific
settings.
User Roles
==========
Each User has a specific **role** which configures their basic permission set of actions they can perform within a Foundry VTT game. The role for each User is configured using the **Configure Players** page described above. Each of the role levels and their meanings are described below:
**None**
The User is blocked from taking actions in Foundry Virtual Tabletop. You can use this role to temporarily or
permanently ban a user from joining the game.
**Player**
The User is able to join the game with permissions available to a standard player. They cannot take some more
advanced actions which require Trusted permissions, but they have the basic functionalities needed to operate
in the virtual tabletop.
**Trusted**
Similar to the Player role, except a Trusted User has the ability to perform some more advanced actions like
create drawings, measured templates, or even to (optionally) upload media files to the server.
**Game Master**
A special User who has administrative control over this specific World. Game Masters behave quite differently
than Players in that they have the ability to see all Entities and Objects within the world as well as the
capability to configure World settings.
**Assistant**
A special User who has many of the same in-game controls as a Game Master User, but does not have the ability
to perform administrative actions like changing User roles or modifying World-level settings.
The Users API
=============
For module developers interested in working with Users, API documentation for scenes and associated classes is available in the :ref:`userAPI` page.
\ No newline at end of file
.. _av:
Audio/Video Chat Integration
****************************
Foundry Virtual Tabletop includes built-in technology to allow for audio/video (A/V) calls shared between all of the players in your game. This is achieved using a technology called *WebRTC* which is a standard specification for Real Time Communications. In order to enable A/V functionality in Foundry VTT, you will need to satisfy some specific requirements.
.. warning:: Most importantly, in order to use built-in AV you need to run Foundry VTT using SSL certificates.
----------
What You Need
=============
The following are requirements in order to use A/V functionality:
* An internet or local network connection to connect and exchange audio and video between players. The download and upload speed needed in order to enjoy this feature will depend on the number of players in your game (and whether they are sending video).
* SSL certificates to enable HTTPS which is a security requirement enforced by the browser in order to capture from your camera and microphone devices
* A signaling server which helps negotiate the connection between players. Foundry VTT does this automatically for you, but you can also use a custom signaling server should you wish.
* A relay server to facilitate communication in cases where it is not possible to establish a direct peer-to-peer connection. Foundry VTT does this automatically for you, but you can also use a custom relay server should you wish.
Why do I need SSL certificates?
-------------------------------
For security reasons, browsers (such as Chrome or Firefox) will not let a website capture your camera and microphone unless that connection is secure. In order for the connection to be secure, the website needs to be access using `https://` rather than `http://`. In order to enable HTTPS support in Foundry VTT, you will need an SSL certificate. You have two choices for that, either you create a valid SSL certificate generated by a trusted Certificate Authority for your domain name, or you create the certificate by yourself. Regardless of the choice you make (and the security concerns with the self signed certificate method), the use of HTTPS is simply to allow the browser to capture from your webcam and microphone and in this case isn't really used to ensure a secure connection between you and your players.
How can I create a self-signed certificate?
-------------------------------------------
Creating your own SSL certificate is easier to achieve so we'll start with that. While it is easier, it does not guarantee security because it does not efficiently encrypt the data transiting over the internet and a hacker, a three-letter government agency or your ISP (Internet Service Provider) could potentially monitor your communications. It is however still more secure than not having an SSL certificate and simply using `http://`
When using a self-signed certificate, your browser will warn you about entering an unsecured site when you visit it for the first time. You will need to click on the 'Advanced' button and then 'Proceed'. Here are some links which explain methods of creating a self-signed certificates for different platforms:
* **Windows**: https://medium.com/the-new-control-plane/generating-self-signed-certificates-on-windows-7812a600c2d8
* **Linux**: https://linuxize.com/post/creating-a-self-signed-ssl-certificate/
* **MacOS**: https://support.apple.com/guide/keychain-access/create-self-signed-certificates-kyca8916/mac
How can I create a trusted certificate?
---------------------------------------
The ideal method for enabling SSL is to create a valid certificate using a trusted Certificate Authority. This process is more complicated, and it requires having a registered domain name which points to your server IP address. If you have bought a domain name or use a web hosting service, you might have the ability to create a valid certificate from your service provider directly. Otherwise, simply follow the instructions provided by the `Let's Encrypt <https://letsencrypt.org/>` project which provides free verified SSL certificates.
----------
A/V Connectivity Guide
======================
To configure Foundry VTT to use the certificate you have created, you need to copy the certificate and the private key to your FVTT's Config directory, and then edit the options.json file and specify the filename of the certificate and the key file under the `sslCert` and `sslKey` fields.
.. figure:: /_static/images/webrtc-mesh-network.jpg
An example visualization of how the mesh network structure works with peer-to-peer calls.
From within the Foundry app, the **AV Configuration** panel is accessible from the Settings sidebar within your active World. This allows you to customize the A/V broadcast mode (including enabling or disabling it), configure a custom signaling or relay server, and designate your preferred webcam and microphone hardware.
Using the Built-In Relay Server
-------------------------------
You can customize the signaling and relay servers used for A/V functionality within the AV Config application accessed through the Settings Sidebar. The Foundry VTT server also acts as a signalling server so there is nothing to do here either. As long as you can connect to FVTT, you are good to go. FVTT also has support for using an external signalling server if you wish and the GameMaster can configure it in the Audio/Video Configuration window under the Server tab. Using a custom server might be preferred if you are having trouble setting up a relaying server, though you can also configure a custom relay server to use directly.
.. note:: When you make an audio or video call using Foundry VTT, every player connects to every other player using peer-to-peer connections.
Unfortunately, due to various factors, two participants in the call may be unable to connect to each other. This can occur due to firewalls or other routing settings which do not work well together. In such (rare) situations, a player may not be able to interface with the call. This can be solved through use of a Relay Server which acts as a middle-point to which both players connect and exchange their audio and video streams. The Foundry VTT server automatically starts a relay server which can be used for your calls - but the built in relay server does require a few things in order to work properly:
- Its own port to listen to connections on
- A big range of ports to be used for relaying
- A publicly accessible IP
If you are self hosting Foundry VTT and you have not done any port forwarding, then the relay server may not work correctly for you. If you are using a server such as AWS or DigitalOcean or any other VPS service, then as long as the proper ports are allowed access to the server, you shouldn't have any issues.
### Foundry's Relay Server
You can use the relay server included with the Foundry VTT server. In the options.json file of the FVTT's Config directory, you can customize its behavior with the following fields (default values are given here if those keys are not specified) :
.. code-block:: none
"turnListeningPort": 33478,
"turnListeningIps": ["0.0.0.0"],
"turnRelayIps": [],
"turnMinPort": 49152,
"turnMaxPort": 65535
If you do not customize those options, then you should setup port forwarding in your router to make sure port 33478 and the port range 49152-65535 are forwarded to your machine properly.
Using a Custom Relay Server
---------------------------
You may run a custom relay server using an external application such as **Coturn**, which is a more advanced relay server which supports things such as relaying over UDP and TCP, using SSL for encrypting relayed data, use of a database for authentication, and many more options, as well as being optimized for heavy traffic production-ready systems. If you use such a custom relay and would like to tell Foundry VTT to use it by default for all players, or you would like to disable the use of the FVTT provided relay server entirely, you can do so by providing an array of configurations in the `turnConfigs` field in the options.json file.
.. code-block:: none
"turnConfigs": [{
"url": "turn:example.com:3478",
"urls": ["turn:example.com:3478", "turns:example.com:5349"],
"username": "my username",
"credential": "my password"
}
]
To disable Foundry's relay server, simply provide an empty list of turn configurations.
----------
Glossary of A/V Related Terminology
===================================
NAT
**Network Address Translation** (routers)
STUN
**Simple Traversal of UDP through NAT** (udp hole-punching through NATs)
TURN
**Traversal Using Relays around NAT** (a relay for data)
ICE
**Interactive Connectivity Establishment** (a methodology for using STUN (and TURN) to ensure a connection between 2 peers)
SDP
**Session Description Protocol** (just text to describe a media stream, think 'json format but for describing media, like "there's audio, here are the codecs we support, here are our list of ICE candidates, etc... ")
RTP
**Real Time Protocol** (protocol used to packetize the audio and video encoded streams over UDP packets)
RTC
**Real Time Communications** (just a broad name that encapsulates all of these technologies (and more) to make them work together so we can have real time communications)
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