Roll20 uses cookies to improve your experience on our site. Cookies enable you to enjoy certain features, social sharing functionality, and tailor message and display ads to your interests on our site and others. They also help us understand how our site is being used. By continuing to use our site, you consent to our use of cookies. Update your cookie preferences .
×
Create a free account

Help me understand "on ready" behavior

1428956138

Edited 1428956313
This is just a simple thing that is baffling me. on("ready", function(){ sendChat("I", "am ready"); }); Executes when I save script, thus spinning up a new sandbox, but doesn't execute when I load the campaign. I thought the ready event fires when a campaign loads and all data has been loaded? Has this changed? EDIT: I'm in the Dev server. Gonna try to reproduce in the regular server. EDIT2: Reproduced.
1428958758
The Aaron
Pro
API Scripter
Try adding a log event in there as well: on("ready", function(){ sendChat("I", "am ready"); log('Sent "I: am ready" chat message.'); }); See if you see the log message in the API Console.
The log seems to work... at least.. if I reload the API page, the console always shows the expected string in the log. The sendChat() only fires when I save scripts.
1428964214
Lithl
Pro
Sheet Author
API Scripter
Check the chat history, perhaps? The sendChat message may be happening before the large green "Welcome to Roll20" banner that appears in the chat pane when you load the VTT.
1428964504
The Aaron
Pro
API Scripter
That's exactly what I was thinking... =D
I ran a bunch of permutations-- loading the campaign, refreshing the page, reloading from the campaign info page, then just completely opening via a fresh browser launch. I'm not getting the sendChat. Also, the log is only happening upon opening the API page. Seems to suggest that on ready is not being fired when the campaign loads at all. I was investigating this because I needed to test some objects reliant on the on ready event without restarting the scripts, which seemed to be clearing the state variable. Now I just can't seem to verify that the on ready event is happening on campaign load.
1428971351

Edited 1428971427
It seems to me that it's functioning like it should: firing when the campaign data is loaded, from the perspective of the API (i.e. when the sandbox spin-up completes). I don't think there is an event that fires when a player connects, if that's what you're trying to catch, but it's my understanding that that's not what "ready" is supposed to be. If restarting the sandbox is wiping state, that sounds like a legit problem (either in the script or in the system), though.
If I'm the only person launching the campaign, as the GM... just me as the 1 user... then that should be the start of some session that fires on ready?
Ok ok... I see something here. It appears that there is some time out for the session at hand. If I launch the campaign after some time away from the site, on ready fires. If I close and launch again, it seems to not recognize a new session. Is anyone aware of this time-out for campaign sessions?
I think I'm back on track now, though I am curious about the session time out and whether I can force a time out for testing purposes.
1428974935
The Aaron
Pro
API Scripter
Ah, I see what you're saying. Manveti is correct, the on('ready') event is for the loading of data into the API sandbox. From: <a href="https://wiki.roll20.net/API:Events#Campaign_Events" rel="nofollow">https://wiki.roll20.net/API:Events#Campaign_Events</a> "This event fires after all the current data for the campaign has been loaded." The Sandbox remains running for some time (I believe I've heard 15 minutes) with no one connected to the Campaign. If you're trying to capture someone connecting to the Campaign, the best way I've found is to set an event on('change:player:_online',...). You may need to use some blend of on('ready',...) and this, because the initial player connecting occurs before the API spins up, so you can't catch that as well. Also, note that the _ on the front of online is required when watching changes for read only properties.
Ok, I can work with that. I was just going nuts trying to figure out why I wasn't getting the on ready when refreshing the campaign. Thanks. I'll call this 'solved.'
1428982564
The Aaron
Pro
API Scripter
No worries! =D
If the sandbox closes after fifteen minutes... there would be no way to catch any events triggering when they load into the campaign though, right?
1429015246
The Aaron
Pro
API Scripter
It's after 15 minutes of inactivity. Probably the events occur, but before scripts have registered for them during on('ready',...). I've not experimented much with registering for events before on('ready',...), but I know you get a bunch of create and modify events for everything on the VTT. I speculate that you wouldn't get the initial player online event as it would be the event that is causing the API to spin up in the first place, but the sending of that event might be either queued or delayed so that it is available. In the case of MotD, where I use this, the first person connecting to a cold campaign does not get the MotD. I have a fix in mind, but haven't implemented it yet.
Indeed, just to confirm, the "ready" event fires when the sandbox spins up, once all of the data for the campaign has been loaded. The sandbox remains active for up to 15 minutes after everyone has "left" the campaign, then when the campaign goes active it spins down. As Aaron said, if you are only wanting to know when people join the game, use the change:player:_online event. If you want to force a sandbox restart, then just click the "Save Changes" button on the API scripts page for the campaign (even if you don't modify the scripts themselves, it will still force a restart of the sandbox).
Thanks for the info, Riley. It all makes sense, now. If I've still got your ear, here, Riley... could you give me two clarifications on related issues? 1. when, if ever, does the state variable get reset? Is the only way to clean it up to set it to undefined so it's old contents will get garbage collected? (I'm mildly ignorant to some javascript details, so feel free to educate my misconceptions.) 2. would the on ready event fire before or after any other API script built an object declared as part of a module?
PS - for everyone's FYI, I was stuck at writing some cleanup code for a module that would make sure some objects were still in sync between the close and start of adjacent sessions. It occurs to me that such a function is probably moot since nothing happens between sessions, but I guess I was trying to account for things like assets possibly going missing from servers, or Roll20 making some change on the backend that could potentially change a campaign without spinning up the sandbox.
1429029670
The Aaron
Pro
API Scripter
In the absence of an answer from on high, I'll give my knowledge on the subject: 1) It is only changed by API scripts. If you want to reset it, you should set it to an empty object: state = {}; scripts expect it to be an object. Finding that it is something else would likely cause them to crash. 2) Ready fires after the sandbox is fully loaded. All your other scripts' objects will have been created by that point, which makes it ideal for second stage linking of scripts. There is no guarantee as to the order that the on('ready',...) will fire between your scripts, but you can be assured that any enabled script has been executed, creating whatever public objects they create. Personally, each of my scripts creates a single object in the global namespace that does nothing but create static data and functions, then register an on('ready',...) event that triggers setting up dynamic structures, finding other installed scripts it depends on, and registers for events with the on() function.
Thanks, Aaron. I've been seeing that design pattern as I study existing scripts. I am taking that into account with this project.