starred/virtualtabletop

Fork 0

mirror of https://github.com/ArnoldSmith86/virtualtabletop.git synced 2026-03-02 22:57:02 -05:00

Docs for Predefined Variables are confusing due to unclear 'active' term #928

New issue

Closed

opened 2026-02-20 10:21:41 -05:00 by deekerman · 5 comments

deekerman commented

2026-02-20 10:21:41 -05:00

Owner

Originally created by @gitran on GitHub (Jan 13, 2026).

This is just a request to clarify some docs.

See the Predefined Variables section of the Functions docs. The word "active" is not well defined. I have finally figured out that "active" does not mean the seat that has turn=true and by extension the player who occupies that seat (which was my naive assumption based on the real world and common term "active player").

For players, active seems to mean connected.
For seats, active seems to mean occupied. (Can a disconnected player be/remain seated?)
seatID, seatIndex, and playerSeats (collection) are confusing because they refer to "the" active player. Do they mean "player clicking the widget" like mouseCoords, playerName, and playerColor?
activeSeats (array and collection) is confusing because while its description seems correct, its name invites the incorrect idea that only the players in those seats are active.

Here is a suggested rewrite based on what I think is the intent. It defines (at the top) a "Context Player" shorthand for "clicker of the widget." Maybe wrongly, I've also clarified "first seat" to mean lowest index value and changed "contains the routine" to "is running the routine."

For the following, the Context Player is the player who triggers the routine.
Each routine begins with a number of predefined variables:

    activeColors - Array of color values for every connected player in the room
    activePlayers - Array of name values for every connected player in the room
    activeSeats - Array of seat id values for seats occupied by players in the activePlayers array
    mouseCoords - Array of the coordinates ([x, y]) of the click made by the Context Player
    playerColor - The color value of the Context Player
    playerName - The name value of the Context Player
    seatID - The id value of the seat in the playerSeats collection that has the lowest index value (or null if playerSeats is empty)
    seatIndex - The index value of the same seat identified by seatID (or null if seatID is null)
    thisID - The id value of the widget that is running the routine

Each routine begins with these predefined collections:

    activeSeats - A collection of the same seats identified by the activeSeats array
    playerSeats - A collection of every seat occupied by the Context Player
    thisButton - A collection of the same widget identified by thisID

Originally created by @gitran on GitHub (Jan 13, 2026). This is just a request to clarify some docs. See the [Predefined Variables section of the Functions docs](https://github.com/ArnoldSmith86/virtualtabletop/wiki/Functions#predefined-variables). The word "active" is not well defined. I have *finally* figured out that "active" does *not mean* the **seat** that has `turn=true` and by extension the **player** who occupies that seat (which was my naive assumption based on the real world and common term "active player"). * For players, active seems to mean connected. * For seats, active seems to mean occupied. (Can a disconnected player be/remain seated?) * `seatID`, `seatIndex`, and `playerSeats` (collection) are confusing because they refer to "the" active player. Do they mean "player clicking the widget" like `mouseCoords`, `playerName`, and `playerColor`? * `activeSeats` (array and collection) is confusing because while its description seems correct, its name invites the incorrect idea that only the players in those seats are active. Here is a suggested rewrite based on what I think is the intent. It defines (at the top) a "Context Player" shorthand for "clicker of the widget." Maybe wrongly, I've also clarified "first seat" to mean lowest index value and changed "contains the routine" to "is running the routine." ``` For the following, the Context Player is the player who triggers the routine. Each routine begins with a number of predefined variables: activeColors - Array of color values for every connected player in the room activePlayers - Array of name values for every connected player in the room activeSeats - Array of seat id values for seats occupied by players in the activePlayers array mouseCoords - Array of the coordinates ([x, y]) of the click made by the Context Player playerColor - The color value of the Context Player playerName - The name value of the Context Player seatID - The id value of the seat in the playerSeats collection that has the lowest index value (or null if playerSeats is empty) seatIndex - The index value of the same seat identified by seatID (or null if seatID is null) thisID - The id value of the widget that is running the routine Each routine begins with these predefined collections: activeSeats - A collection of the same seats identified by the activeSeats array playerSeats - A collection of every seat occupied by the Context Player thisButton - A collection of the same widget identified by thisID ```

deekerman

2026-02-20 10:21:41 -05:00

closed this issue
added the
documentation
label

deekerman commented

2026-02-20 10:21:42 -05:00

Author

Owner

@gitran commented on GitHub (Jan 13, 2026):

Hmm. I suppose "first seat" might actually mean "next in the (forward) turn cycle, starting with the one currently assigned turn=true"? Either way, "first seat" is not a particularly clear way of describing what the code is doing.

@gitran commented on GitHub (Jan 13, 2026): Hmm. I suppose "first seat" might actually mean "next in the (forward) turn cycle, starting with the one currently assigned `turn=true`"? Either way, "first seat" is not a particularly clear way of describing what the code is doing.

deekerman commented

2026-02-20 10:21:42 -05:00

Author

Owner

@96LawDawg commented on GitHub (Jan 13, 2026):

Thanks for the feedback. Those are all good points. We know what we meant, but that isn't helpful to newcomers. I made most of your changes. I did not like defining something by referencing something else, but I did include a "see ..." comment.

Your initial take on first seat was mostly correct, but I think my changes made it even more clear. When you get a chance, please take a look at the revisions live on the wiki page now and let us know what you think.

Also, are you in our Discord channel. If so, what username?

@96LawDawg commented on GitHub (Jan 13, 2026): Thanks for the feedback. Those are all good points. We know what we meant, but that isn't helpful to newcomers. I made most of your changes. I did not like defining something by referencing something else, but I did include a "see ..." comment. Your initial take on first seat was mostly correct, but I think my changes made it even more clear. When you get a chance, please take a look at the revisions live on the wiki page now and let us know what you think. Also, are you in our Discord channel. If so, what username?

deekerman commented

2026-02-20 10:21:42 -05:00

Author

Owner

@gitran commented on GitHub (Jan 13, 2026):

I'm satisfied. I like Invoking Player better than Context Player. My ideal but impossible fix is to rename a bunch of these variables.

I'm not on Discord.

@gitran commented on GitHub (Jan 13, 2026): I'm satisfied. I like Invoking Player better than Context Player. My ideal but impossible fix is to rename a bunch of these variables. I'm not on Discord.

deekerman commented

2026-02-20 10:21:42 -05:00

Author

Owner

@96LawDawg commented on GitHub (Jan 13, 2026):

No worries about Discord. We just have a category for wiki contributor and I was going to add you there. And your fix will not happen. Not worth the squeeze. But thank you for making the wiki better. If you find anything else, let us know.

@96LawDawg commented on GitHub (Jan 13, 2026): No worries about Discord. We just have a category for wiki contributor and I was going to add you there. And your fix will not happen. Not worth the squeeze. But thank you for making the wiki better. If you find anything else, let us know.

deekerman commented

2026-02-20 10:21:42 -05:00

Author

Owner

@96LawDawg commented on GitHub (Jan 13, 2026):

Oh yeah. If you need any help working on a game, join the Discord.

@96LawDawg commented on GitHub (Jan 13, 2026): Oh yeah. If you need any help working on a game, join the Discord.