Maptool: Initiative Events

[mikehenry-se]

Is your feature request related to a problem? Please describe.
I'm trying to update tokens when they get the initiative and reset all tokens a new round starts (or ends).

Describe the solution you'd like
I'd be happy to see two new events; e.g. onNextInitiative(Token) and onRoundStarted(TokenList) that can be implemented and which are 1) called when a token receives the initiative through the "next" button with the token, and 2) when a new round is started, with all the tokens in the initiative list as the argument. Of course, the arguments are nice-to-haves.

Describe alternatives you've considered
I'm doing it now with a separate macro but it would be cleaner and easier to use if it hooked into the existing initiative framework, rather than remembering to push separate buttons for this.

Thanks in advance!

[Phergus]

Related to #720

[selquest]

@cwisniew Is this actually in progress or tied up in an ongoing rewrite somewhere? I'm looking to make some incremental improvements to Initiative this weekend, and I feel like there are some steps that can be taken here even before #1827 and related things. If we're not committed to deferring this, my thought was to add support for onInitiativeChange() using an approach similar to the existing onTokenMove().

[cwisniew]

@selquest this was waiting on expanding of the event system so we could do everything in a consistent way. I guess this depends on if we are going to do a large refactor for other things, if so its not so important to wait, but that something we are still deciding on.

[selquest]

I was exploring this a little further out of curiosity, and my proof of concept turned into what I think is a pretty good basic implementation. Up to you folks whether it's worth merging of course, but I think that given how often it's come up here and on discord, it probably makes sense to get a basic implementation out. Since it's based so heavily on onTokenMove, any future changes to the event mechanisms shouldn't have too much added complexity for needing to handle this one too.

[selquest]

Two new initiative events added.

• onInitiativeChangeRequest - called when the initiative is changing, can deny the change by setting init.denyChange to 1. Unlike _onTokenMove_, this event can have macros on multiple Lib:Tokens. All matching handlers will be called, and the change will be denied if at least one denial is received.
• onInitiativeChange - called once an initiative change has been approved and is being applied. Also supports multiple Lib:Tokens.

These events currently effect only the next/previous initiative operations (whether triggered via macro or the Panel), meaning that any mechanism for jumping directly to a specific initiative slot (the setCurrentInitiative() function, the Make Current panel action, etc.) will bypass these events. This is largely an attempt to avoid undue modifications to the InitiativeList internals, but also ensures that the GM always has a way of forcing an initiative change without the need to muck about with any macros. If we later decide to make other kinds of changes trigger these events, we'll need to provide some optional parameters and other mechanisms for skipping them.

Here's a sample of the JSON passed into the event macros:

{
  "old":   {
    "round": 1,
    "offset": 3,
    "initiative": "-2.3",
    "holding": 0,
    "token": "7FD82A2533C74DF3B8480F6625AB0EBC"
  },
  "new":   {
    "round": 1,
    "offset": 4,
    "initiative": "ABC",
    "holding": 0,
    "token": "FF81F6365AAD4215B7E3758C36C765D1"
  },
  "direction": "NEXT"
}

_Note: when starting the first round, the "old" portion of this will have some special values:_

{
  "old":   {
    "round": -1,
    "offset": -1,
    "initiative": "",
    "holding": 0,
    "token": ""
  },
  "new":   {
    "round": 1,
    "offset": 0,
    "initiative": "22",
    "holding": 0,
    "token": "2F12FEEE06B54B639228DBE56CE451AA"
  },
  "direction": "NEXT"
}

[Phergus]

Documentation begun on Guide to Initiative Events.
Need to add init.denyChange to the special variables page and the new events to the events page.

[mikehenry-se]

Great work team! Based on the excellent doc, I think the suggested solution will be very workable and simplify my Cepheus Engine framework considerably. Can't wait to dig my teeth into this!
-_Sketchy_

[selquest]

Yup, will do - was waiting for the second PR to be merged before I propagated those new names all over the place ;)

[selquest]

Added page for init.denyChange, and redirects for onInitiativeChange, onInitiativeChangeRequest that will show up on the List of Events page but just redirect to the Guide.

Also added references to the events in the pages for nextInitiative() and prevInitiative()

[Phergus]

Tested. Events and control variable working as expected.