GUI features: runScript and namedEvent

[stgatilov]

There was an idea to add two features to GUI scripts (6164).

The first one is runScript command, which allows GUI script to call a function from game script.
Interestingly, this feature is already supported in the GUI engine, but the game code only processes this command when the player clicks left mouse button on the GUI (i.e. usually it works in onAction handler, but not in namedEvent or onTime handlers).

Obviously, ID initially did not envision runScript as a global feature which works the same way everywhere, their idea was that it is context-sensitive, and whoever calls the GUI code can then pull the commands generated by the call and do whatever he wants with them.
I'm not sure I really want to change this architecture...

Anyway: what are the possible use cases for runScript command?

The second feature is namedEvent command, which simply generates/calls a named event with specified name on the whole UI, which can be then handled by matching onNamedEvent handlers.

However, this command can be implemented in several ways:

1. Whenever namedEvent command is executed, the named event is processed immediately. The rest of the script (after namedEvent command) is continued only after generated named event is fully processed.
2. Whenever namedEvent command is executed, named event is put into some kind of queue, then the current script continues to execute. The generated named event is executed at some moment later, but surely on the current frame.
3. The point 2 can be further differentiated on the exact order when generated named events are processed.

So the first approach is how functions normally behave in normal imperative languages, with a real call stack.
The second approach is delayed execution, like what we currently do with "resetTime X; -> X::onTime 0 {...}" combo (at least everywhere in the main menu GUI).

My worry with the first approach is that it is an major change for GUI engine with no past experience, and it will probably not match well with the long-established GUI wierdness (I mean e.g. the wierdness that all expressions in GUI script are executed before the script commands start executing).
And it would work different both from the "resetTime + onTime 0" combo.

On the other hand, the callGui in game scripts do execute named event immediately.
And I must admit nested GUI calls could be used to reduce the issues from the GUI weirdness mentioned above.

Also, this command exists in Quake 4, but I'm not sure how exactly it works.
And it's probably good idea to make TDM work the same way.

[boissiere]

These are my initial thoughts for possible use cases (copied from the linked bug tracker entry).

1) In the recent thread

@datiswous asked if it was possible to develop a template for an enhanced type of briefing where people could specify a different background for each page of text (possibly by having different xdata items for each page)
2) It would also make it easier to develop a in-game journal type of readable which is added to when the player does certain actions. A current example of this is done in the first mission (Monastery) of a House of Locked Secrets but the implementation is quite cumbersome because
a) Each xdata item contains the whole contents of the 'previous' xdata item plus the added text.
b) The in-game actions have to be performed in a pre-determined order.
3) Readables could be made more sophisticated e.g. having tabbed pages (e.g. in a paper address book).
4) You could have dynamic entity guis (e.g. destination displays at railway stations which change when the train has left).

I'm willing to expand on these if needed

Edited October 11, 2023 by boissiere

[HMart]

Nice knowing you are looking at this.  

Btw when I made my own version of "namedEvent" gui cmd, I just copied the convention of other gui cmds like the "localSound" cmd, what I found is that it made the usage of simple nameEvents in GUI's very fast, with no need to mess with c++ and compile the engine. I think exactly the same reason quake 4 developers said they implemented it, thou like you said we don't know how they made their version. 

Perhaps is why I had some issues with my implementation when trying to call more complex onNamedEvents, so is something that needs to be well tested.

Simple example of usage (the following code is untested and should be looked as "pseudo" code)

windowDef Desktop
{
	rect	0,0,640,480
	backcolor 0,0,0,1
	menugui 1
	
	float "text_state" 0
	
	onInit {
		// just in case ...
		if("Desktop::text_state" != 0) {
			set "Desktop::text_state" "0";
		}	
	}
	
	//*************** Events *************************
	onNamedEvent ClearText {
		set "Text::text" "";
		set "Desktop::text_state" "0";
	}
	
	onNamedEvent SetText {
		set "Text::text" "Hello world";
		set "Desktop::text_state" "1";
	}
	//************************************************
	
	
	windowDef Text
	{
		rect	240,41,165,110
		visible	1
		forecolor	1,1,1,1
		text	""
		textscale	0.5
		font	"fonts/micro"
		textalign	1
	}
	
	windowDef back_btn
	{
		rect (320-55),(240-35),50,30
		visible 1
		text	"Click Me"
		textalign 1
		textscale	0.3
		font	"fonts/an"
		
		
		onActionRelease {
			if("Desktop::text_state" == 1){
				namedEvent "ClearText";
			} else {
				namedEvent "SetText";
			}
		}
	}
}

 

Edited October 12, 2023 by HMart

[stgatilov]

  

23 hours ago, boissiere said:

These are my initial thoughts for possible use cases (copied from the linked bug tracker entry).

I guess I'll copy my answer too.

Quote

1) In the recent thread @datiswous asked if it was possible to develop a template for an enhanced type of briefing where people could specify a different background for each page of text (possibly by having different xdata items for each page)
2) It would also make it easier to develop a in-game journal type of readable which is added to when the player does certain actions. A current example of this is done in the first mission (Monastery) of a House of Locked Secrets but the implementation is quite cumbersome
3) Readables could be made more sophisticated e.g. having tabbed pages (e.g. in a paper address book).

I think all these use cases are blocked by the fact the TDM core readable scripts don't support them.

If you want to use TDM's readable code, then you have to respect its boundaries/interface. If it does not normally support something, then you can't do it while using them, regardless of what features GUI scripting or game scripting supports.

On the other hand, let's suppose someone is willing to implement a fully custom GUI + script, without support --- i.e. no readable.guicode, no xdata, etc.
In this case, he needs to put control logic somewhere.

Putting it both in GUI code and game scripts would generate confusion, bugs, and maybe even race conditions.
Putting it only on GUI side is bad simply because GUI scripting is bad.
The only viable solution is to put all the logic into game script.

But if all the logic is in game script, then GUI does not need the runScript command.
It should only set some of its own gui variables as "requests", so that later the game script could detect these requests and process them.
At least that's how TDM core readable support works.

[datiswous]

15 hours ago, stgatilov said:

I think all these use cases are blocked by the fact the TDM core readable scripts don't support them.

If you want to use TDM's readable code, then you have to respect its boundaries/interface. If it does not normally support something, then you can't do it while using them, regardless of what features GUI scripting or game scripting supports.

Can someone override core readable scripts for their mission?

[boissiere]

1 hour ago, datiswous said:

Can someone override core readable scripts for their mission?

It's funny you should ask that because I've been thinking about this a bit and am now wondering if my use cases 2 and 3 (more dynamic in-game readables) are actually possible with the existing system.

I'm not sure you would want to actually override the existing scripts but more likely add in new scripts into the existing system. I might have a go at at this weekend.

[stgatilov]

6 hours ago, datiswous said:

Can someone override core readable scripts for their mission?

You can probably write a new one, and use it in your readables.
If you override existing one, the next change in core will break your mission.

The only question is: is there any hardcoded stuff in C++ connected to readables?

[Geep]

I rather regret that the namedEvent and runScript ideas were put in the same bugtracker request, since they each clearly justify their own topic.

From the discussion above, it seems that namedEvent would be easier/safer to implement this round.

It appears runScript is more problematic, and furthermore, may not be the only or best way to implement new capabilities for readables. The latter (e.g., tabs, different backdrops for different pages) probably also needs a separate bugtracker item.

Turning to namedEvent...

@stgatilov in the OP was wondering about whether the in-GUI call to namedEvent should be synchronous (i.e., happen immediately) or asynchronous. Synchronous is easier for the script writer to think about, and would be my preference. As he indicates, this would be less like other gui script aspects (some of them "weird"), but more like calls to gui named events from doomscript. And, by introducing nested call stacks, he thinks may provide future opportunities for reduction in weirdness.

It is unclear to me if HMart's implementation is synchronous or asynchronous.

Probably we should not worry about whether this usage is consistent with Quake 4, since we'll probably never know.

[HMart]

On 12/5/2023 at 6:53 PM, Geep said:

It is unclear to me if HMart's implementation is synchronous or asynchronous.

My implementation is just a simple gui script cmd, is very naive and just follows the same system of other existing gui script cmds, made by idSoftware.

I have zero idea if is synchronous or asynchronous that is beyond my expertise, nor if it is the same as done in Quake 4.

Plus like I said above I do remember experiencing some small problems with it, when trying to use it to call more complex namedEvent's, that may be connected to the "synchronous or asynchronous" stuff.