Bot players are used to fill in when there are not enough people to start a multiplayer world, or when a player leaves during a world.
How the bot player behaves needs to be implemented for each content.
This guide describes the general method of creating a Bot player.
The Bot Player creation guide is based on the multiplayer guide. [Multiplay Tutorial]
STEP 1: Create a Bot Player
1-1. Add a boolean value called IsBot to the multiplayer schema.
1-2. Define the function below to create a Bot player in the server script index.ts and call it at the desired point.
// The `CreateBot()` method is used to create a bot player with the given `userId`.
CreateBot(userId: string) {
// Generate a session ID for the bot player using the provided `userId`.
const sessionId = "Bot_" + userId;
// Check if a bot player with the same session ID already exists. If so, return without creating a duplicate.
if (this.state.players.has(sessionId)) {
return;
}
// Create a new `Player` object for the bot player.
const player: Player = new Player();
player.sessionId = sessionId;
if (userId) {
player.zepetoUserId = userId;
}
player.isBot = true;
// Add the bot player to the state's players map using the session ID as the key.
this.state.players.set(player.sessionId, player);
this._botMap.set(sessionId, player);
}
Tips
- The userId of a specific user is stored in advance for the Bot player character to be created.
- You can check the UserId of a specific user by checking the userId of the client connecting to OnJoin on the server. After writing the script below in the server script, connect from the relevant world.
onJoin(client: SandboxPlayer) {
console.log(client.userId);
}
STEP 2: Create a Bot player on the client
2-1. If you have the server create a Bot player at some point, the client will recognize it as a new player in OnJoinPlayer().
- Create Project > Create > ZEPETO > TypeScript and rename it to BotPlayerManager.
- Add logic in OnAddedPlayer() to create each player, and add logic to distinguish bot players and create their ZEPETO characters.
import { ZepetoCharacter, ZepetoPlayers } from 'ZEPETO.Character.Controller';
import { Room } from 'ZEPETO.Multiplay';
import { ZepetoScriptBehaviour } from 'ZEPETO.Script'
import { ZepetoWorldMultiplay } from 'ZEPETO.World';
export default class BotPlayerManager extends ZepetoScriptBehaviour {
public zepetoWorldMultiplay: ZepetoWorldMultiplay;
// Private variables to store the current room and bot player data.
private _room: Room;
private _botMapData: Map<string, ZepetoCharacter> = new Map<string, ZepetoCharacter>();
Start() {
// Listen for the `RoomJoined` event from the `ZepetoWorldMultiplay` component.
this.zepetoWorldMultiplay.RoomJoined += (room: Room) => {
this._room = room;
}
// Listen for the `OnAddedPlayer` event from `ZepetoPlayers.instance` to handle newly added players.
ZepetoPlayers.instance.OnAddedPlayer.AddListener((userId: string) => {
// Get the current player data from the room state using the `userId`.
const currentPlayer = this._room.State.players.get_Item(userId);
// Check if the player is a bot, and if so, set them as a bot player.
if (currentPlayer.isBot) {
this.SetBotPlayer(currentPlayer.sessionId);
}
});
}
}
2-2. Write the SetBotPlayer function to add tags and synchronization components to bot players and create scripts to control them.
- Set _botMapData to save bot player data in Map format to manage bot players.
// The `SetBotPlayer()` method is used to set a player as a bot.
SetBotPlayer(userId: string) {
// Get the ZEPETO character associated with the bot player using their `userId`.
const bot = ZepetoPlayers.instance.GetPlayer(userId).character;
// Set the name of the character to the `userId` for identification.
bot.gameObject.name = userId;
// Store the bot player's data in the `_botMapData` map using their `userId` as the key.
this._botMapData.set(userId, bot);
}
Tips
You can add additional scripts or settings to SetBotPlayer() to control the behavior of bot players.
STEP 3: Create a Bot player button on the client
For worlds that require a certain number of players to start, sometimes there are not enough players and you have to wait a long time for the world to start.
In this case, you can start the world by adding a Bot player.
3-1. Register a function to execute CreateBot() when the server receives a message from the client in index.ts.
async OnCreate() {
// Handle the "CreateBot" message, which creates a bot player with the given userId.
this.onMessage("CreateBot", (client, message) => {
this.CreateBot(message);
});
}
3-2. In the client script BotPlayerManager.ts, write a function to send the "CreateBot" message to the server.
- The way to execute a function is to send a message by pressing a button.
- Send the user ID of the Bot player to be created as a string through the message.
public buttonCreateBot: Button;
public botPlayerId: string;
Start() {
// Add a click listener to the "Create Bot" button to send a message to create a bot player.
this.buttonCreateBot.onClick.AddListener(() => {
this._room.Send("CreateBot", this.botPlayerId);
});
}
3-3. Now, when you run the server and the runtime, you can see that bot players are created when you press the button.
STEP 4: Start the world by adding a bot player
When there are not enough players to start the world, you can add bot players to initiate the world.
4-1. In the server script, add the following code during OnJoin to check the number of players and start the world when there are at least four players.
- Add a function to check the number of players in CreateBot().
- Add a counter for the number of plays in the StartWorld() function.
async onJoin(client: SandboxPlayer) {
// Check the number of players in the room after a player joins.
this.CheckPlayerNumber();
}
// The `CheckPlayerNumber()` method checks the number of players in the room and starts the world if there are at least four players.
CheckPlayerNumber() {
// Print the current number of players in the room to the console.
console.log(`player Number, ${this.state.players.size}`);
// If there are at least four players in the room, start the world.
if (this.state.players.size >= 4) {
this.StartWorld();
}
}
// The `CreateBot()` method is used to create a bot player with the given `userId`.
CreateBot(userId: string) {
// Generate a session ID for the bot player using the provided `userId`.
const sessionId = "Bot_" + userId;
// Check if a bot player with the same session ID already exists. If so, return without creating a duplicate.
if (this.state.players.has(sessionId)) {
return;
}
// Create a new `Player` object for the bot player.
const player: Player = new Player();
player.sessionId = sessionId;
if (userId) {
player.zepetoUserId = userId;
}
player.isBot = true;
// Add the bot player to the state's players map using the session ID as the key.
this.state.players.set(player.sessionId, player);
this._botMap.set(sessionId, player);
// Check the number of players in the room after adding the bot player.
this.CheckPlayerNumber();
}
private playTime: number = 0;
// The `StartWorld()` method increments the play time and broadcasts the "StartWorld" message to all clients.
StartWorld() {
this.playTime += 1;
// Print a message indicating the start of the world and the current play time.
console.log("Start World!");
this.broadcast("StartWorld", this.playTime);
}
Tips
- On the server, OnJoin is executed when a real player joins the room. So, when a Bot player is created via CreateBot and when a player enters via OnJoin, checkPlayerNumber() adds the number of people.
4-2. In the client script, BotPlayerManager.ts, write StartWorld(), which is executed when the message StartWorld is received from the server.
Start() {
// Listen for the `RoomJoined` event from the `ZepetoWorldMultiplay` component.
this.zepetoWorldMultiplay.RoomJoined += (room: Room) => {
// Add a message handler for the "StartWorld" message type.
this._room.AddMessageHandler("StartWorld", (playTime: number) => {
this.StartWorld(playTime);
});
}
// The `StartWorld()` method is called when the world starts with the provided `playTime`.
StartWorld(playTime: number) {
// Print the world start message along with the `playTime`.
console.log(`Start World : ${playTime}`);
}
4-3. At runtime, when there are more than 4 players, including Bot players, you can see a log called World Start pops up on the server console and on the client's console.
STEP 5: Synchronize Bot Player Position
Below is sample code that moves the added Bot players to the local player position and synchronizes the movement position.
5-1. First, write the code to move the Bot players when the message MoveBot is received from the client in index.ts of the server.
async OnCreate() {
// Handle the "MoveBot" message, which moves the bot player to the specified position.
this.onMessage("MoveBot", (client, message) => {
this.MoveBot(client, message);
});
}
// The `MoveBot()` method moves the bot player to the specified position based on the received message.
MoveBot(client: SandboxPlayer, message: string) {
// Parse the JSON message received from the client to extract the position information.
const position = JSON.parse(message);
// Create a new message object with the user's session ID and the parsed position data.
const newMessage = {
user: client.sessionId,
positionX: position.x,
positionY: position.y,
positionZ: position.z
}
// Broadcast the "MoveBotToPosition" message to all clients with the new message data as a JSON string.
this.broadcast("MoveBotToPosition", JSON.stringify(newMessage));
}
5-2. In the client script, BotPlayerManager.ts, write SendBotPosition() that sends the local player position to the server when buttonCallBot is pressed.
- Then write code to move all Bot players to the location information included in the message when the message MoveBotToPosition is received from the server.
public buttonCallBot: Button;
Start(){
// Listen for the `RoomJoined` event from the `ZepetoWorldMultiplay` component.
this.zepetoWorldMultiplay.RoomJoined += (room: Room) => {
this._room = room;
// Add a message handler for the "StartWorld" message type.
this._room.AddMessageHandler("StartWorld", (playTime: number) => {
this.StartWorld(playTime);
});
// Add a click listener to the "Call Bot" button to send a message to send a bot player position.
this.buttonCallBot.onClick.AddListener(() => {
this.SendBotPosition();
});
}
// This method sends the position of the local player's character to the server for bot movement synchronization.
SendBotPosition() {
// Get the position of the local player's character.
const localPlayerPosition = ZepetoPlayers.instance.LocalPlayer.zepetoPlayer.character.transform.position;
// Create a position object containing the x, y, and z coordinates of the local player's character.
const position = {
x: localPlayerPosition.x,
y: localPlayerPosition.y,
z: localPlayerPosition.z
}
// Convert the position object to a JSON string and send it to the server with the "MoveBot" message type.
this._room.Send("MoveBot", JSON.stringify(position));
}
MoveBotToPosition(message) {
// Parse the JSON message received from the client to extract the position information.
const jsonMessage = JSON.parse(message);
const position = new Vector3(jsonMessage.positionX, jsonMessage.positionY, jsonMessage.positionZ);
// Move each bot character in the `_botMapData` map to the specified position with a small random offset on the x and z axes.
this._botMapData.forEach((character: ZepetoCharacter) => {
// The `MoveToPosition()` method is used to move the character to the specified position.
// Here, a small random offset is added to the target position to create a natural-looking movement for the bots.
character.MoveToPosition(position + new Vector3(Random.Range(0.5, 1), 0, Random.Range(0.5, 1)));
});
}
5-3. Now if you create a Bot player at runtime and press the buttonCallBot button you should see the created Bot player move to the local player character position.
BotPlayerManager.ts full code
import { Random, Vector3 } from 'UnityEngine';
import { Button } from 'UnityEngine.UI';
import { ZepetoCharacter, ZepetoPlayers } from 'ZEPETO.Character.Controller';
import { Room } from 'ZEPETO.Multiplay';
import { ZepetoScriptBehaviour } from 'ZEPETO.Script'
import { ZepetoWorldMultiplay } from 'ZEPETO.World';
export default class BotPlayerManager extends ZepetoScriptBehaviour {
// Public properties to reference necessary components and settings from the Inspector.
public zepetoWorldMultiplay: ZepetoWorldMultiplay;
public buttonCreateBot: Button;
public buttonCallBot: Button;
public botPlayerId: string;
// Private variables to store the current room and bot player data.
private _room: Room;
private _botMapData: Map<string, ZepetoCharacter> = new Map<string, ZepetoCharacter>();
Start() {
// Listen for the `RoomJoined` event from the `ZepetoWorldMultiplay` component.
this.zepetoWorldMultiplay.RoomJoined += (room: Room) => {
this._room = room;
// Add a message handler for the "StartWorld" message type.
this._room.AddMessageHandler("StartWorld", (playTime: number) => {
this.StartWorld(playTime);
});
}
// Listen for the `OnAddedPlayer` event from `ZepetoPlayers.instance` to handle newly added players.
ZepetoPlayers.instance.OnAddedPlayer.AddListener((userId: string) => {
// Get the current player data from the room state using the `userId`.
const currentPlayer = this._room.State.players.get_Item(userId);
// Check if the player is a bot, and if so, set them as a bot player.
if (currentPlayer.isBot) {
this.SetBotPlayer(currentPlayer.sessionId);
}
});
// Add a click listener to the "Create Bot" button to send a message to create a bot player.
this.buttonCreateBot.onClick.AddListener(() => {
this._room.Send("CreateBot", this.botPlayerId);
});
this.zepetoWorldMultiplay.RoomJoined += (room: Room) => {
this._room = room;
this._room.AddMessageHandler("MoveBotToPosition", (message: string) => {
this.MoveBotToPosition(message);
});
}
// Add a click listener to the "Call Bot" button to send a message to send a bot player position.
this.buttonCallBot.onClick.AddListener(() => {
this.SendBotPosition();
});
}
// The `SetBotPlayer()` method is used to set a player as a bot.
SetBotPlayer(userId: string) {
// Get the ZEPETO character associated with the bot player using their `userId`.
const bot = ZepetoPlayers.instance.GetPlayer(userId).character;
// Set the name of the character to the `userId` for identification.
bot.gameObject.name = userId;
// Store the bot player's data in the `_botMapData` map using their `userId` as the key.
this._botMapData.set(userId, bot);
}
// The `StartWorld()` method is called when the world starts with the provided `playTime`.
StartWorld(playTime: number) {
// Print the world start message along with the `playTime`.
console.log(`Start World : ${playTime}`);
}
// This method sends the position of the local player's character to the server for bot movement synchronization.
SendBotPosition() {
// Get the position of the local player's character.
const localPlayerPosition = ZepetoPlayers.instance.LocalPlayer.zepetoPlayer.character.transform.position;
// Create a position object containing the x, y, and z coordinates of the local player's character.
const position = {
x: localPlayerPosition.x,
y: localPlayerPosition.y,
z: localPlayerPosition.z
}
// Convert the position object to a JSON string and send it to the server with the "MoveBot" message type.
this._room.Send("MoveBot", JSON.stringify(position));
}
// This method is called when the server receives the "MoveBot" message from a client and moves the bot characters to the specified position.
MoveBotToPosition(message) {
// Parse the JSON message received from the client to extract the position information.
const jsonMessage = JSON.parse(message);
const position = new Vector3(jsonMessage.positionX, jsonMessage.positionY, jsonMessage.positionZ);
// Move each bot character in the `_botMapData` map to the specified position with a small random offset on the x and z axes.
this._botMapData.forEach((character: ZepetoCharacter) => {
// The `MoveToPosition()` method is used to move the character to the specified position.
// Here, a small random offset is added to the target position to create a natural-looking movement for the bots.
character.MoveToPosition(position + new Vector3(Random.Range(0.5, 1), 0, Random.Range(0.5, 1)));
});
}
}
index.ts server full code
import { Sandbox, SandboxOptions, SandboxPlayer } from "ZEPETO.Multiplay";
import { DataStorage } from "ZEPETO.Multiplay.DataStorage";
import { Player, Transform, Vector3 } from "ZEPETO.Multiplay.Schema";
export default class extends Sandbox {
storageMap: Map<string, DataStorage> = new Map<string, DataStorage>();
// Save the bot player's map data as _botMap
private _botMap: Map<string, Player> = new Map<string, Player>();
private playTime: number = 0;
constructor() {
super();
}
onCreate(options: SandboxOptions) {
// Called when the Room object is created.
// Handle the state or data initialization of the Room object.
this.onMessage("onChangedTransform", (client, message) => {
this.state.players.get(client.sessionId);
const player = this.state.players.get(client.sessionId);
const transform = new Transform();
transform.position = new Vector3();
transform.position.x = message.position.x;
transform.position.y = message.position.y;
transform.position.z = message.position.z;
transform.rotation = new Vector3();
transform.rotation.x = message.rotation.x;
transform.rotation.y = message.rotation.y;
transform.rotation.z = message.rotation.z;
if (player) {
player.transform = transform;
}
});
this.onMessage("onChangedState", (client, message) => {
const player = this.state.players.get(client.sessionId);
if (player) {
player.state = message.state;
player.subState = message.subState;
}
});
// Handle the "CreateBot" message, which creates a bot player with the given userId.
this.onMessage("CreateBot", (client, message) => {
this.CreateBot(message);
});
// Handle the "MoveBot" message, which moves the bot player to the specified position.
this.onMessage("MoveBot", (client, message) => {
this.MoveBot(client, message);
});
}
// The `CreateBot()` method is used to create a bot player with the given `userId`.
CreateBot(userId: string) {
// Generate a session ID for the bot player using the provided `userId`.
const sessionId = "Bot_" + userId;
// Check if a bot player with the same session ID already exists. If so, return without creating a duplicate.
if (this.state.players.has(sessionId)) {
return;
}
// Create a new `Player` object for the bot player.
const player: Player = new Player();
player.sessionId = sessionId;
if (userId) {
player.zepetoUserId = userId;
}
player.isBot = true;
// Add the bot player to the state's players map using the session ID as the key.
this.state.players.set(player.sessionId, player);
this._botMap.set(sessionId, player);
// Check the number of players in the room after adding the bot player.
this.CheckPlayerNumber();
}
// The `CheckPlayerNumber()` method checks the number of players in the room and starts the world if there are at least four players.
CheckPlayerNumber() {
// Print the current number of players in the room to the console.
console.log(`player Number, ${this.state.players.size}`);
// If there are at least four players in the room, start the world.
if (this.state.players.size >= 4) {
this.StartWorld();
}
}
// The `StartWorld()` method increments the play time and broadcasts the "StartWorld" message to all clients.
StartWorld() {
this.playTime += 1;
// Print a message indicating the start of the world and the current play time.
console.log("Start World!");
this.broadcast("StartWorld", this.playTime);
}
// The `MoveBot()` method moves the bot player to the specified position based on the received message.
MoveBot(client: SandboxPlayer, message: string) {
// Parse the JSON message received from the client to extract the position information.
const position = JSON.parse(message);
// Create a new message object with the user's session ID and the parsed position data.
const newMessage = {
user: client.sessionId,
positionX: position.x,
positionY: position.y,
positionZ: position.z
}
// Broadcast the "MoveBotToPosition" message to all clients with the new message data as a JSON string.
this.broadcast("MoveBotToPosition", JSON.stringify(newMessage));
}
async onJoin(client: SandboxPlayer) {
// Create the player object defined in schemas.json and set the initial value.
console.log(`[OnJoin] sessionId : ${client.sessionId}, HashCode : ${client.hashCode}, userId : ${client.userId}`)
const player = new Player();
player.sessionId = client.sessionId;
if (client.hashCode) {
player.zepetoHash = client.hashCode;
}
if (client.userId) {
player.zepetoUserId = client.userId;
}
// [DataStorage] DataStorage Load of the entered Player
const storage: DataStorage = client.loadDataStorage();
this.storageMap.set(client.sessionId, storage);
let visit_cnt = await storage.get("VisitCount") as number;
if (visit_cnt == null) visit_cnt = 0;
console.log(`[OnJoin] ${client.sessionId}'s visiting count : ${visit_cnt}`)
// [DataStorage] Update Player's visit count and then Storage Save
await storage.set("VisitCount", ++visit_cnt);
// Manage the Player object using sessionId, a unique key value of the client object.
// The client can check the information about the player object added by set by adding the add_OnAdd event to the players object.
this.state.players.set(client.sessionId, player);
// Check the number of players in the room after a player joins.
this.CheckPlayerNumber();
}
onTick(deltaTime: number): void {
// It is repeatedly called at each set time in the server, and a certain interval event can be managed using deltaTime.
}
async onLeave(client: SandboxPlayer, consented?: boolean) {
// By setting allowReconnection, it is possible to maintain connection for the circuit, but clean up immediately in the basic guide.
// The client can check the information about the deleted player object by adding the add_OnRemove event to the players object.
this.state.players.delete(client.sessionId);
}
}