Map Management - rpg-sage-creative/rpg-sage GitHub Wiki

Map Management

Yes, you heard that right, we can do maps! All you have to do is create a metadata text file that has a name ending in .map.txt and then drop the file in the channel you want your map. Sage will take it from there!

Note about prototype.

This feature is still a prototype, perhaps consider it an alpha release. The interface and feedback aren't as clean as we want and the execution of features is a tad clumsy. But, we assure you that we already have planned improvements that will make it much better!

Note about image storage.

RPG Sage doesn't store any images used in the creation of maps. Therefore, you will need to make sure that they are all public urls that will be available until you are no longer using the map. The simplest way to do this is to post the image(s) into a discord channel and then grab the url from the uploaded image(s).

Importing a Map

RPG Sage has the ability to render maps and allow GMs and Players to move tokens on that map. The images must be publicly available on the internet via url (http/https). You can build a map using our Map Builder and export the file needed to import your map. By posting that file as an attachment, RPG Sage will attempt to import and render your map.

Map Controls

Movement Arrows (left side)

Move your active token (or terrain if GM) one square in the direction indicated.

Gear

Disabled; saved for future use.

Mountain

GM uses this button to cycle through the terrain images to select the active terrain.

Yellow Circle

Cycle through aura images (for the active token) to select the active aura. A token can have any number of auras configured, but only one can be active at a time. (This limit of active auras also applies to terrain for GMs.)

Person

Cycle through token images to select the active token. Players can only cycle through tokens assigned to them. GMs cycle through all tokens. If you are using RPG Sage's Game feature, a PC's token (along with familiars/companions) should be added automatically to the map when trying to select their token. (There is a known bug in the current code that will likely spawn a PC's token even if you already assigned them a token when making the map.)

Up and Down Arrows (right side)

GMs can use this to reorder (alter the z-index) of the terrain and tokens.

Red X

GM uses this button to delete terrain / tokens. The thought was you import a map for an encounter with all baddies and delete them as they are removed from play.

Activating Tokens

Instead of cycling through your map tokens, you can simply activate the one you want:

sage! map activate terrain="Quicksand"
sage! map activate token="BaddieA"
sage! map activate name="Wizard Hero"
sage! map activate aura="Wizard Hero Aura"

Note: For terrain or aura or token use the name given in the map file (NOT case sensitive). For name can use either the token name given in the map file or the name/alias of the character in the Game.

Moving Tokens

Moving Tokens by Posting Compass or Ordinal Directions

This command allows you to move your token more than one square at a time. You must reply to the map that you are moving tokens on. The compass directions are read from a "path" argument (or brackets in the command if a path argument isn't found), in order, separated by spaces. Before moving your token, you will get a confirmation prompt that lists movement by using arrows to point in the directions you indicated. You may use compass or ordinal directions, and you may mix and match.

Valid Compass Direction Values:

NW, N, NE, W, E, SW, S, SE

Valid Ordinal Direction Values:

UL, U, UR, L, R, DL, D, DR

Arrow Character Output:

↖, ⬆, ↗, ⬅, ➡, ↙, ⬇, ↘

Movement Examples

You move your current token/terrain with:

sage! map move [S3 SE E3]
sage! map move path="S3 SE E3"

sage! map move [D3 DR R3]
sage! map move path="D3 DR R3"

You move a terrain/token by name with:

sage! map move terrain="tree" [S3 SE E3]
sage! map move terrain="tree" path="S3 SE E3"

sage! map move token="fighter" [D3 DR R3]
sage! map move token="fighter" path="D3 DR R3"

You move a token linked to a game character by character name with:

sage! map move name="Wally the Wizard" [S3 SE E3]
sage! map move name="Wally the Wizard" path="D3 DR R3"

You bulk move terrain/tokens with:

sage! map move terrain="tree,rock,fire" [S3 SE E3]
sage! map move terrain="tree,rock,fire" path="S3 SE E3"
sage! map move terrain="tree,rock,fire" terrainPath="S3 SE E3"

sage! map move tokens="fighter1,fighter2,fighter3" [S3 SE E3]
sage! map move tokens="fighter1,fighter2,fighter3" path="S3 SE E3"
sage! map move tokens="fighter1,fighter2,fighter3" tokensPath="S3 SE E3"

You can use an asterisk to bulk move similarly named terrain/tokens with:

sage! map move terrain="fire*" [S3 SE E3]
sage! map move terrain="fire*" path="S3 SE E3"
sage! map move terrain="fire*" terrainPath="S3 SE E3"

sage! map move tokens="fighter*" [S3 SE E3]
sage! map move tokens="fighter*" path="S3 SE E3"
sage! map move tokens="fighter*" tokensPath="S3 SE E3"

You can also move a terrain/token as a name="path" combo:

sage! map move tree="S3 SE E3"
sage! map move fighter="S3 SE E3"

You can combine most of the previous options to bulk move terrain/tokens and move other items in other directions:

sage! map move tree="S3" fighter="N N N" terrain="rock,fire" terrainPath="S S E" tokens="fighter*" tokensPath="5NW"

Map File Contents

A map file consists of "blocks" that detail each image you want on the map. The four types of block are: map (the map's background image), terrain (a moveable piece of terrain/trap/hazard), aura (a toggleable aura that moves with a token/terrain), token (a pc/npc). The layers are drawn from the bottom to top (map, terrain, aura, token) and initially drawn in the order listed in the file within each layer (you can change their draw order later via the interface). Only the first map layer will be drawn. Each block must have the url to the image and the name of the image (in the case of the [map] block, this is the name of the map that RPG Sage will display).

`[map]` (background image/layer)

url the url to the image
name the name of the map
grid this number of columns (first) and rows (second), ex: 24x11
spawn = the column (left) and row (right) where where new tokens appear, ex: 2,1

`[terrain]` (bottom layer)

url the url to the image
name the name of the terrain or object
size the width (first) and height (second) of terrain, ex: 1x1
position the starting column (left) and row (right) on the map, ex: 3,2

(Only a GM can move an object of this layer)

`[aura]` (middle layer)

url the url to the image (yes, it requires images for now)
name the name of the aura
anchor the name of the token (or terrain) to anchor the aura to
opacity how transparent the image is (0% - 100%), ex: 50%
size the width (first) and height (second) of aura, ex: 1x1
position the column (left) and row (right) on the map relative to anchor
- A 5 ft. emanation from a 1x1 token would have an anchor, size=3x3, and position=-1,-1
- (Auras will change greatly in the next iteration.)

[token] top layer

url the url to the image
name the name of the PC or NPC
size the width (first) and height (second) of token, ex: 1x1
scale the image scaling factor, ex: 1.5
position the starting column (left) and row (right) on the map, ex: 3,2
user the Discord handle of the User to assign ownership of the token (PCs only): @PlayerName#1234

Map File Example

[map]
https://rpgsage.io/images/docs/map/example/ForgedFacadeReveal.png
name=Forged Facade Reveal
grid=7x10
spawn=4,1

[token]
https://rpgsage.io/images/docs/map/example/Hoobla.png
name=Hoobla
size=1x1
position=4,7
user=@Randal#7243

[token]
https://rpgsage.io/images/docs/map/example/BaltaramToken.png
name=Baltaram
size=1x1
position=4,2

[token]
https://rpgsage.io/images/games/ftp-756/YellowCircle.png
name=Bodyguard (Yellow)
size=1x1
position=3,2

[token]
https://rpgsage.io/images/games/ftp-756/BlueCircle.png
name=Bodyguard (Blue)
size=1x1
position=4,3

[token]
https://rpgsage.io/images/games/ftp-756/PurpleCircle.png
name=Bodyguard (Purple)
size=1x1
position=5,2