FEATURE: Table functions

Developer discussion regarding MapTool 1.4

Moderators: dorpond, trevor, Azhrei

Forum rules
Posting now open to all registered forum users.
User avatar
Jagged
Great Wyrm
Posts: 1306
Joined: Mon Sep 15, 2008 9:27 am
Location: Bristol, UK

FEATURE: Table functions

Post by Jagged »

As a group we have been talking about including some database functionality into Maptool and as a precursor to that, we realised that from the point of view of the macro scripting language, table functionality was woefully inadequate. So the following functions will be coming soon to a Maptool near you!


getTableNames() function
Returns a list containing the names of the tables in the campaign. The type of the value returned depends on the delimiter parameter. The function can be used by players or from a non-trusted macro, but it will only return player-visible tables. When used by a GM or a trusted macro it returns all tables.
Usage:

Code: Select all

getTableNames()
getTableNames(delim)

If the delimiter is not specified then a string list is returned with the default value of "," is used.
If the delimiter json then a JSON Array is returned.
Otherwise a string list is returned with the delimiter passed in.
Examples:

Code: Select all

[r:getTableNames()]
[r:getTableNames("<br>")]
[r:getTableNames("json")]


createTable() function
Creates an empty table, specifying its access levels and optional image. May only be used by GM or a trusted macro.
Usage:

Code: Select all

createTable(tableName, visible, accessible)
createTable(tableName, visible, accessible, imageId)

TableName is the identifier for the table.
Visible specifies whether or not the table can be seen by players in the Table Window. Values may be either 1 (true) or 0 (false).
Accessible specifies whether or not the table can be used by players to lookup values. Values may be either 1 (true) or 0 (false).
ImageId is optional and is the asset id of an image that will be used for the table in the Table Window. If an invalid or missing asset id is used, the table will display a red "X".
Examples:

Code: Select all

[r:createTable("tableX",1,1)]
[r:createTable("tableY",1,1,getTableImage("tableZ"))]


deleteTable() function
Removed the specified table from the campaign. May only be used by GM or a trusted macro.
Usage:

Code: Select all

deleteTable(tableName)

tableName specifies the table to be deleted.

addTableEntry() function
Adds a new row to the specified table. May only be used by GM or a trusted macro.
Note: adding a row to a table will not automatically change the table row value, so this should be updated to avoid possible errors.
Usage:

Code: Select all

addTableEntry(tableName,rangeStart,rangeEnd,result)
addTableEntry(tableName,rangeStart,rangeEnd,result,imageId)

tableName specifies the table to which the row will be added.
rangeStart is the lowest integer value that will return the row when the table is accessed by a "table" function call.
rangeEnd is the highest integer value that will return the row when the table is accessed by a "table" function call.
result is the value to be returned by a "table" function call.
ImageId is optional and is the asset id of an image that will be returned by a "tableImage" function call.
Examples:

Code: Select all

[r:addTableEntry("test",1,3,"bert")]
[r:addTableEntry("test",4,4,"fred")]
[r:addTableEntry("test",5,5,"alf", getTokenImage())]
[r:setTableRoll("test","")]


deleteTableEntry() function
Removes a row from the specified table. May only be used by GM or a trusted macro.
Note: deleting a row from a table will not automatically change the table row value, so this should be updated to avoid possible errors.
Usage:

Code: Select all

deleteTableEntry(tableName,roll)

tableName specifies the table from which the row will be removed.
roll is the value that specifies the row to be removed.
Examples:

Code: Select all

[r:addTableEntry("test",1,3,"bert")]
[r:deleteTableEntry("test",2)]
[r:setTableRoll("test","")]
Last edited by Jagged on Mon May 02, 2016 4:20 pm, edited 2 times in total.

User avatar
wolph42
Deity
Posts: 9831
Joined: Fri Mar 20, 2009 5:40 am
Location: Netherlands
Contact:

Re: FEATURE: Table functions

Post by wolph42 »

Woot! coolbeans, that would mean I can finally scratch the xls sheet I have for this.

Now the *only* thing this lacks is 'addTableColumn'... and I know, that would require an entire new table system. But still one keeps dreaming...

somehow that reminds me of this conversation

User avatar
Jagged
Great Wyrm
Posts: 1306
Joined: Mon Sep 15, 2008 9:27 am
Location: Bristol, UK

Re: FEATURE: Table functions

Post by Jagged »

getTableRoll() function
Returns the roll expression for the specified table. May only be used by GM or a trusted macro.
Usage:

Code: Select all

getTableRoll(tableName)

tableName specifies the table from which the roll expression will be returned.

setTableRoll() function
Returns the roll expression for the specified table. May only be used by GM or a trusted macro.
Usage:

Code: Select all

getTableRoll(tableName, roll)

tableName specifies the table from which the roll expression will be returned.
roll contains the new roll expression. If the value is "" the roll will be set to a default expression that should cover all table entries.
Examples:

Code: Select all

[r:setTableRoll("test","")]
[r:setTableRoll("test","1d6+1")]


clearTable() function
Removes all rows from the specified table. May only be used by GM or a trusted macro.
Usage:

Code: Select all

clearTable(tableName)


getTableVisible () function
Returns either 1 (true) or 0 (false) depending upon whether or not the table is visible to players.
Usage:

Code: Select all

getTableVisible (tableName)


setTableVisible() function
Sets whether or not the specified table is visible to players. May only be used by GM or a trusted macro.
Usage:

Code: Select all

setTableVisible(tableName, 0)


getTableAccess () function
Returns either 1 (true) or 0 (false) depending upon whether or not the table may be accessed by players.
Usage:

Code: Select all

getTableAccess(tableName)


setTableAccess() function
Sets whether or not the specified table may be accessed by players. May only be used by GM or a trusted macro.
Usage:

Code: Select all

setTableAccess(tableName, 0)
Last edited by Jagged on Thu Apr 21, 2016 9:16 am, edited 1 time in total.

User avatar
Jagged
Great Wyrm
Posts: 1306
Joined: Mon Sep 15, 2008 9:27 am
Location: Bristol, UK

Re: FEATURE: Table functions

Post by Jagged »

wolph42 wrote:Now the *only* thing this lacks is 'addTableColumn'... and I know, that would require an entire new table system. But still one keeps dreaming...


That will come :)

Although it will probably be a different system for compatibility reasons.

User avatar
aliasmask
Deity
Posts: 8653
Joined: Tue Nov 10, 2009 6:11 pm
Location: Bay Area

Re: FEATURE: Table functions

Post by aliasmask »

How do we know how many rows there are in a table? I suppose we can create our own index to keep track.

I'm guessing in your example to remove a row that if the value falls in to a ranges value that the range will be removed but all the values will remain. When adding a row I imagine it fills in the first empty range found and then overwrites the result and image. Is that correct?

Btw, this is epic for MT. Now we have access to essentially global variables. We can now store an image library without having to actually have tokens on a map somewhere.

User avatar
Full Bleed
Demigod
Posts: 4553
Joined: Sun Feb 25, 2007 11:53 am
Location: MD
Contact:

Re: FEATURE: Table functions

Post by Full Bleed »

Thanks for this. :)


Can we get a sortTable() function? Some of my tables are quite out of sorts.

And a couple other suggestions:

getGMTableNames()
copyTable() or duplicateTable()
Maptool is the Millennium Falcon of VTT's -- "She may not look like much, but she's got it where it counts."

User avatar
Jagged
Great Wyrm
Posts: 1306
Joined: Mon Sep 15, 2008 9:27 am
Location: Bristol, UK

Re: FEATURE: Table functions

Post by Jagged »

copyTable() function
Creates a new table based upon an existing table. May only be used by GM or a trusted macro.
Usage:

Code: Select all

copyTable(oldTable, newTable)

oldTable specifies the table which will be copied.
newTable is the name of the new table.

setTableEntry() function
Sets the result for a specified roll value. Returns true (1) if update successful and false (0) if not. May only be used by GM or a trusted macro.
Usage:

Code: Select all

setTableEntry(tableName, roll, result)

tableName specifies the table to be updated.
roll is the value that specifies the row to be updated.
result is the new result for the specified row.
Last edited by Jagged on Fri Apr 22, 2016 3:31 pm, edited 1 time in total.

User avatar
wolph42
Deity
Posts: 9831
Joined: Fri Mar 20, 2009 5:40 am
Location: Netherlands
Contact:

Re: FEATURE: Table functions

Post by wolph42 »

aliasmask wrote:Btw, this is epic for MT. Now we have access to essentially global variables. We can now store an image library without having to actually have tokens on a map somewhere.


nice thought!

this makes me wonder: would it also be possible to store an entire table structure as a property on a token (without the images, just the data?). Reason I ask, maptool is still easiest to work with with drag and drop and it would be great to have a token which you drop onto a map, run a macro and you have all your tables set up. Way less hassle and way more control than import export table!

User avatar
aliasmask
Deity
Posts: 8653
Joined: Tue Nov 10, 2009 6:11 pm
Location: Bay Area

Re: FEATURE: Table functions

Post by aliasmask »

yeah, the result table holds any data. Could be a single value or a complicated json. Any string really. You can put macro code in there if you wanted.

User avatar
Jagged
Great Wyrm
Posts: 1306
Joined: Mon Sep 15, 2008 9:27 am
Location: Bristol, UK

Re: FEATURE: Table functions

Post by Jagged »

I think token libraries or code libraries are definitely things we want to add. But we will do that through a dedicated db tool, rather than by extending the table function.

User avatar
Jagged
Great Wyrm
Posts: 1306
Joined: Mon Sep 15, 2008 9:27 am
Location: Bristol, UK

Re: FEATURE: Table functions

Post by Jagged »

aliasmask wrote:I'm guessing in your example to remove a row that if the value falls in to a ranges value that the range will be removed but all the values will remain.


If you imaging the table UI, the "deleteTableEntry" command removes one row from the table. It finds the row that would be returned for the roll value, and then removes that row. It does not change the values for any other row. There is no data integrity here ;)

Sorry I missed this question.

aliasmask wrote:When adding a row I imagine it fills in the first empty range found and then overwrites the result and image. Is that correct?

This works exactly the same as the table UI. "addTableEntry" just adds a new row. There is no data integrity and there is nothing to stop you entering values that would cause potential errors when the table is used.

Just like the UI ;)

User avatar
Full Bleed
Demigod
Posts: 4553
Joined: Sun Feb 25, 2007 11:53 am
Location: MD
Contact:

Re: FEATURE: Table functions

Post by Full Bleed »

Since you've been knee-deep in the table code recently, I was wondering if it made sense to give MT some options for a table lookup path.

Right now, tables are always embedded in a campaign file. And that makes a lot of sense for core tables... but it might end up being a bit of a hurdle when trying to use tables for larger database type usage (i.e. an image/token repository for a bestiary).

Having a way to access tables outside the campaign file (in a local directory or something like dropbox) would be a way to keep core campaign files smaller while still allowing the creation and usage of some massive tables. The time it takes to save a campaign file (or auto backup), for example, is reflective of the size of a campaign file. So while it would be nice to be able to quickly deploy any monster from a massive bestiary table, increasing the size of the campaign file to accommodate that could have some significant downsides (i.e. more chance of corrupted campaign files, longer save/load times, etc.)
Maptool is the Millennium Falcon of VTT's -- "She may not look like much, but she's got it where it counts."

User avatar
Jagged
Great Wyrm
Posts: 1306
Joined: Mon Sep 15, 2008 9:27 am
Location: Bristol, UK

Re: FEATURE: Table functions

Post by Jagged »

I (and the other current developers) have been putting a lot of thought into these very issues :)

No designs decisions have yet been made. For example it may be easier to achieve the same kind of thing using better import/export tools. But we are definitely considering how best to handle external data. We are still at the very early stages of thought.

If we do come to any conclusions, we will post here before we commit to anything.

User avatar
celestian
Dragon
Posts: 276
Joined: Mon May 17, 2010 3:29 pm

Re: FEATURE: Table functions

Post by celestian »

These are some very useful functions!

Question: does ROLL have to be a integer? Can it be a string?

User avatar
RPTroll
TheBard
Posts: 3148
Joined: Tue Mar 21, 2006 7:26 pm
Location: Austin, Tx
Contact:

Re: FEATURE: Table functions

Post by RPTroll »

aliasmask wrote:Btw, this is epic for MT. Now we have access to essentially global variables. We can now store an image library without having to actually have tokens on a map somewhere.


That's brilliant.
ImageImage ImageImageImageImage
Support RPTools by shopping
Image
Image

Post Reply

Return to “MapTool 1.4”