Player-Specific Custom UI

When building a UI panel, a common scenario is to display different content for

each player. An example is the button hover color, which should only be shown to
the player interacting with the button, but not all players. (Therefore, you can
see that the hover state implementation in the previous section is in fact
incorrect, because the button background color will change when any player hovers
onto the button.) Another example would be players’ HUD (heads-up display) where we
obviously want to show different numbers and stats for each player.
One straightforward way to achieve this is to duplicate the entity and set the
visibility of each entity so that it is only visible to one player. We actually
recommend using the Local Mode when adopting this approach. Please see a more
detailed discussion and examples in the Local Mode section. But there are cases
where we don’t want to have multiple UI gizmos, and want to keep one single panel
that is publicly visible. Custom UI feature allows us to display different content
to each player on the same UI Gizmo . This is achieved by only updating the value
of a Binding to certain players, thus creating a player-specific value for them.
Setting New Values for Only Certain Players
The set() method of the Binding can take an optional second parameter of an array
of players.
When the set() method is called without an array of players, the new value (we call
it the global value ) is updated to everyone; when it is called with an array of
players, only those players will receive the new value of the Binding (we call it
the player value).
// Everyone gets the new value, and everyone's UI is re-rendered
someBinding.set(newValue);

// Only player1 and player2 get the new value and a UI re-render;
// everyone else stays unaffected
someBinding.set(newValue, [player1, player2]);
Therefore, the correct implementation for the button with hover state needs to take
the acting player into account, and only manipulate the player specific value:
function MyButton(props: MyButtonProps): UINode {
...
return Pressable({
children: Text({ text: props.label, style: { ... } }),
onClick: props.onClick,
onEnter: player => backgroundColor.set(HOVERED_COLOR, [player]),
onExit: player => backgroundColor.set(DEFAULT_COLOR, [player]),
style: { backgroundColor, ... },
}),
}
Global Value vs Player Values
Conceptually, it would be helpful to explicitly make a distinction between the
“global value” and the “player values.” A player would see the global value by
default; however, if there is a player value set for a player, that player will see
the player value. Another way to think about global value is that, when a new
player joins the world, that player will always receive the global values as the
initial values.
The behavior of the set() method of the Binding can be more accurately described
as:
When the set() method is called with an array of players, we are effectively
setting a new player value for those players in the array. In this case, the global
value is left unchanged, so other players that are not in the array will be
unaffected.
When the set() method is called without an array of players, we are updating the
global value, and clearing all player values. As a result, all players will receive
the new value, regardless of whether they have any player values in the past.
As you can see, player values can be seen as “deviations” from the global value.
Therefore, we also provide a reset() method, which will remove the player values,
effectively setting the Binding back to the global value. Like the set() method,
the reset() method also takes an optional array of players, which indicates who we
should reset for. If provided, only those players in the array will have their
player values reset and receive the global value; if not provided, all player
values will be cleared. With the introduction of the reset() method, we can have an
even simpler implementation for the button hover state. We may treat the default
color as the global value, and the hovered color as the player value, then instead
of setting it back to the default color, we simply need to reset the Binding:
function MyButton(props: MyButtonProps): UINode {
const backgroundColor = new Binding<string>('#19AD0E');

return Pressable({
children: Text({ ... }),
onClick: props.onClick,
onEnter: player => backgroundColor.set('#87D481', [player]),
onExit: player => backgroundColor.reset([player]),
style: { backgroundColor, ... },
}),
}
What about Map Functions?
Other than the straightforward way of directly setting a new value, we sometimes
use a map function to get new values, for example in functional updates and derived
values for a Binding. Is the map function acting on the global value or the player
values?
The answer is both! It is worth noting that both functional update and derived
values respect player values. The map function will be used to mutate/derive both
the global value and each player value that the Binding might have. To illustrate
this in a concrete example:
// global player1 player2 player3
const binding = new Binding(0);
// binding 0 0 0 0
binding.set(1);
// binding 1 1 1 1
binding.set(2, [player1, player2]);
// binding 1 2 2 1
binding.set(v => v + 1);
// binding 2 3 3 2
const derived = binding.derive(v => v + 1);
// binding 2 3 3 2
// derived 3 4 4 3
binding.set(4, [player2, player3]);
// binding 2 3 4 4
// derived 3 4 5 5
binding.set(v => v + 1, [player3]);
// binding 2 3 4 5
// derived 3 4 5
Setting Player Values on Start
Sometimes we want to set player values for each player before the player interacts
with the UI. We can check this.world.getPlayers() to get the existing players and
connect the OnPlayerEnterWorld event to get the new players. For example, a simple
“Welcome, [player’s name]!” text would be:
class WelcomeMessage extends UIComponent {
initializeUI() {
const message = new Binding<string>('Welcome!');

// for existing players

this.world.getPlayers().forEach(
player => message.set(`Welcome, ${player.name.get()}!`, [player]),
);
 // for new players
this.connectCodeBlockEvent(
this.entity,
CodeBlockEvents.OnPlayerEnterWorld,
player => message.set(`Welcome, ${player.name.get()}!`, [player]),

return Text({ text: message });

}
Player-Specific UI Example – A Case Study
Let’s work on a more interesting and complicated example. Say we want to put a
“Waiting for X players” text and a “Get Ready” button at the entrance of a game.
When a player clicks on the button, the button becomes “Cancel” and clicking again
will cancel the ready state. When X reaches zero, the button disappears and the
text comes “Go!”.
There are many different approaches to this problem. Depending on our familiarity
with Bindings and the concept of state management, we might find one easier than
the others. Let’s imagine two creators, Alice and Bob, and let’s see how they will
implement this UI differently, and we can compare the approaches in the end.
Alice is familiar with object-oriented programming and is comfortable about setting
each property of each UI component. She looks at the UI, and realizes that there
are three things that will get updated at runtime: the text prompt, the button
label, and the button visibility. Alice decides to create a Binding for each of
them.
class GetReadyDialog extends UIComponent {
initializeUI() {
const textPrompt = new Binding<string>(
'Waiting for 8 players',
);
const buttonLabel = new Binding<string>('Get Ready');
const showButton = new Binding<boolean>(true);

return View({
children: [
Text({ text: textPrompt }),
UINode.if(
showButton,
Pressable({
children: Text({ text: buttonLabel }),
onClick: /** TODO: button effect */,
}),
),
],
});
}
}
She correctly realizes that the only time any of these Bindings might get updated
is when any player clicks the button, so it’s sufficient to update all of the
Bindings inside the onClick callback. Also, she realizes that the button label
should only be updated to the player clicking the button, but the text prompt and
the button visibility need to be updated for all players.
class GetReadyDialog extends UIComponent {
initializeUI() {
const textPrompt = new Binding<string>(
'Waiting for 8 players',
);
const buttonLabel = new Binding<string>('Get Ready');
const showButton = new Binding<boolean>(true);
 return View({
children: [
Text({ text: textPrompt }),
UINode.if(
showButton,
Pressable({
children: Text({ text: buttonLabel }),
onClick: player => {
// only change the acting player's button label
if ( /** TODO: if the player has clicked */ ) {
buttonLabel.set('Get Ready', [player]);
} else {
buttonLabel.set('Cancel', [player]);
}

// change everyone's prompt and button visibility

if ( /** TODO: if there are remaining slots */ ) {
textPrompt.set(
`Waiting for ${remainingSlots} players`,
);
} else {
textPrompt.set('Go!');
showButton.set(false);
}
},
}),
),
],
});
}
}
She struggles a little bit with the condition she should put into those clauses,
but eventually she figured it out. She should keep track of who has clicked the
button or not. Once she has that, she can easily tell if there are any remaining
slots, and if a particular player has clicked the button or not. She decides to
create a set to track this.
class GetReadyDialog extends UIComponent {
initializeUI() {
const readyPlayers = new Set();
const textPrompt = new Binding<string>('Waiting for 8 players');
const buttonLabel = new Binding<string>('Get Ready');
const showButton = new Binding<boolean>(true);

return View({
children: [
Text({text: textPrompt}),
UINode.if(
showButton,
Pressable({
children: Text({text: buttonLabel}),
onClick: player => {
if (readyPlayers.has(player)) {
readyPlayers.delete(player);
buttonLabel.set('Get Ready', [player]);
} else {
readyPlayers.add(player);
buttonLabel.set('Cancel', [player]);
}
 const remainingSlots = 8 - readyPlayers.size;
if (remainingSlots > 0) {
textPrompt.set(`Waiting for ${remainingSlots} players`);
} else {
textPrompt.set('Go!');
showButton.set(false);
}
},
}),
),
],
});
}
}
Bob, on the other hand, is following the suggestions from this documentation.
Unlike Alice, he doesn’t immediately care about what the UI needs to render. He
decides to first think about a minimal but complete representation of the UI. He
realizes that, to decide what needs to be rendered in the UI, he needs to know the
number of remaining slots, which will be used to derive the text prompt and the
button visibility; he also needs to know whether the player has clicked the button
or not, which will be used to derive the button label.
class GetReadyDialog extends UIComponent {
initializeUI() {
const remainingSlots = new Binding<number>(8);
const hasClicked = new Binding<boolean>(false);

return View({
children: [
Text({
text: remainingSlots.derive(r =>
r > 0 ? `Waiting for ${r} players` : 'Go!',
),
}),
UINode.if(
remainingSlots.derive(r => r > 0),
Pressable({
children: Text({
text: hasClicked.derive(h =>
h ? 'Cancel' : 'Get Ready',
),
}),
onClick: /** TODO: button effect */,
}),
),
],
});
}
}
Like Alice, Bob also realizes that he needs to update the two Bindings in the
onClick callback, and that hasClicked should be updated only to the player clicking
the button, and remainingSlots should be updated to everyone. When both of those
Bindings are updated, the new value should depend on the old one, so he uses
functional update.
class GetReadyDialog extends UIComponent {
initializeUI() {
const remainingSlots = new Binding<number>(8);
const hasClicked = new Binding<boolean>(false);

return View({
 children: [
Text({
text: remainingSlots.derive(r =>
r > 0 ? `Waiting for ${r} players` : 'Go!',
),
}),
UINode.if(
remainingSlots.derive(r => r > 0),
Pressable({
children: Text({
text: hasClicked.derive(h =>
h ? 'Cancel' : 'Get Ready',
),
}),
onClick: player => {
// only change click status for the acting player
hasClicked.set(h => !h, [player]);

// remaining slots should be updated for everyone

remainingSlots.set(r => r +
(/** TODO: if the player has clicked */ ? 1 : -1)
);
},
}),
),
],
});
}
}
The final missing piece is that he needs to update the remainingSlots depending on
the value of hasClicked. How does he access this value? He realizes that he already
did access this value inside the functional update for hasClicked. Now all he has
to do is to put the remainingSlots update inside the functional update of
hasClicked. This is a bit complicated to think about, but works perfectly.
class GetReadyDialog extends UIComponent {
initializeUI() {
const remainingSlots = new Binding<number>(8);
const hasClicked = new Binding<boolean>(false);

return View({
children: [
Text({
text: remainingSlots.derive(r =>
r > 0 ? `Waiting for ${r} players` : 'Go!',
),
}),
UINode.if(
remainingSlots.derive(r => r > 0),
Pressable({
children: Text({
text: hasClicked.derive(h => (h ? 'Cancel' : 'Get Ready')),
}),
onClick: player => {
hasClicked.set(
h => {
remainingSlots.set(r => r + (h ? 1 : -1));
return !h;
},
[player],
 );
},
}),
),
],
});
}
}
Now that we have seen two implementations of the same UI from Alice and Bob, which
one is better?
Alice thinks hers is better, because she explicitly maintains a set of players who
have clicked the button, so it’s easier to debug if anything goes wrong. It is also
easier to talk to other scripts in her game if other scripts need the same
information.
Bob thinks his implementation is better. There are fewer Bindings, and the code in
general is more concise. All the states are controlled by the Bindings, so he
doesn’t need to manually make sure the external storage and the Bindings are
synced.
So which one is better? It is completely up to you! The “correct” choice depends on
many factors: your familiarity with different techniques, the coding styles set by
your team, how your scripts talk to the rest of your gaming state management
system, etc. This section is not choosing one coding style for you. Rather, it is
demonstrating the capabilities of the Custom UI feature for you to better
understand the pros and cons of each approach.
Player-specific Bindings and UIs are powerful tools, but would require some time to
get used to. Happy coding!