From 07ee9ccb5887344d2176a1ba96e3488b0a6cfba2 Mon Sep 17 00:00:00 2001 From: Paul Pacheco Date: Tue, 1 Oct 2019 11:27:00 -0500 Subject: [PATCH] docs: move custom player docs to correct place --- doc/Guides/CustomPlayer.md | 87 ------------------- doc/Guides/GameObjects/SpawnPlayerCustom.md | 95 +++++++++++++++------ doc/Guides/toc.yml | 2 - 3 files changed, 70 insertions(+), 114 deletions(-) delete mode 100644 doc/Guides/CustomPlayer.md diff --git a/doc/Guides/CustomPlayer.md b/doc/Guides/CustomPlayer.md deleted file mode 100644 index 1c95441df..000000000 --- a/doc/Guides/CustomPlayer.md +++ /dev/null @@ -1,87 +0,0 @@ -# Custom Players - -Many games need character customization. You may want to pick the color of the hair, eyes, skin, height, race, etc. - -By default Mirror will instantiate the player for you. While that is convenient, it might prevent you from customizing it. Mirror provides the option of overriding player creation and customize it. - -1) Create a class that extends `NetworkManager` if you have not done so. For example: - -``` cs -public class MMONetworkManager : NetworkManager -{ - ... -} -``` -and use it as your Network manager. - -2) Open your Network Manager in the inspector and disable the "Auto Create Player" Boolean. - -3) Create a message that describes your player. For example: - -``` cs -public class CreateMMOCharacterMessage : MessageBase -{ - public Race race; - public string name; - public Color hairColor; - public Color eyeColor -} - -public enum Race -{ - None, - Elvish, - Dwarvish, - Human -} -``` - -4) Create your player prefabs (as many as you need) and add them to the "Register Spawnable Prefabs" in your Network Manager, or add a single prefab to the player prefab field in the inspector. - -5) Send your message and register a player: - -``` cs -public class MMONetworkManager : NetworkManager -{ - public override void OnStartServer() - { - base.OnStartServer(); - - NetworkServer.RegisterHandler(OnCreateCharacter); - } - - public override void OnClientConnect(NetworkConnection conn) - { - base.OnClientConnect(conn); - - // you can send the message here, or wherever else you want - CreateMMOCharacterMessage characterMessage = new CreateMMOCharacterMessage() - { - race = Race.Elvish, - name = "Joe Gaba Gaba", - hairColor = Color.Red, - eyeColor = Color.Green - } - - conn.Send(characterMessage); - } - - void OnCreateCharacter(NetworkConnection conn, CreateMMOCharacterMessage message) - { - // playerPrefab is the one assigned in the inspector in Network - // Manager but you can use different prefabs per race for example - GameObject gameobject = Instantiate(playerPrefab); - - // Apply data from the message however appropriate for your game - // Typically Player would be a component you write with syncvars or properties - Player player = gameobject.GetComponent(); - player.hairColor = message.hairColor; - player.eyeColor = message.eyeColor; - player.name = message.name; - player.race = message.race; - - // call this to use this gameobject as the primary controller - NetworkServer.AddPlayerForConnection(conn, player); - } -} -``` diff --git a/doc/Guides/GameObjects/SpawnPlayerCustom.md b/doc/Guides/GameObjects/SpawnPlayerCustom.md index a1ba7b380..67bbbf3ef 100644 --- a/doc/Guides/GameObjects/SpawnPlayerCustom.md +++ b/doc/Guides/GameObjects/SpawnPlayerCustom.md @@ -1,46 +1,91 @@ -# Custom Player Spawning +# Custom Character Spawning -The Network Manager offers a built-in simple player spawning feature, however you may want to customize the player spawning process - for example to assign a color to each new player spawned. +Many games need character customization. You may want to pick the color of the hair, eyes, skin, height, race, etc. -To do this you need to override the default behavior of the Network Manager with your own script. +By default Mirror will instantiate the player for you. While that is convenient, it might prevent you from customizing it. Mirror provides the option of overriding player creation and customize it. -When the Network Manager adds a player, it also instantiates a game object from the Player Prefab and associates it with the connection. To do this, the Network Manager calls `NetworkServer.AddPlayerForConnection`. You can modify this behavior by overriding `NetworkManager.OnServerAddPlayer`. The default implementation of `OnServerAddPlayer` instantiates a new player instance from the player Prefab and calls `NetworkServer.AddPlayerForConnection` to spawn the new player instance. Your custom implementation of `OnServerAddPlayer` must also call `NetworkServer.AddPlayerForConnection`, but your are free to perform any other initialization you require in that method too. - -The example below customizes the color of a player. First, add the Player script to the player prefab: +1) Create a class that extends `NetworkManager` if you have not done so. For example: ``` cs -using UnityEngine; -using Mirror; -class Player : NetworkBehaviour +public class MMONetworkManager : NetworkManager { - [SyncVar] - public Color color; + ... +} +``` +and use it as your Network manager. + +2) Open your Network Manager in the inspector and disable the "Auto Create Player" Boolean. + +3) Create a message that describes your player. For example: + +``` cs +public class CreateMMOCharacterMessage : MessageBase +{ + public Race race; + public string name; + public Color hairColor; + public Color eyeColor +} + +public enum Race +{ + None, + Elvish, + Dwarvish, + Human } ``` -Next, create a custom Network Manager to handle spawning. +4) Create your player prefabs (as many as you need) and add them to the "Register Spawnable Prefabs" in your Network Manager, or add a single prefab to the player prefab field in the inspector. + +5) Send your message and register a player: ``` cs -using UnityEngine; -using Mirror; - -public class MyNetworkManager : NetworkManager +public class MMONetworkManager : NetworkManager { - public override void OnServerAddPlayer(NetworkConnection conn, AddPlayerMessage extraMessage) + public override void OnStartServer() { - GameObject player = Instantiate(playerPrefab); - player.GetComponent().color = Color.red; + base.OnStartServer(); + + NetworkServer.RegisterHandler(OnCreateCharacter); + } + + public override void OnClientConnect(NetworkConnection conn) + { + base.OnClientConnect(conn); + + // you can send the message here, or wherever else you want + CreateMMOCharacterMessage characterMessage = new CreateMMOCharacterMessage() + { + race = Race.Elvish, + name = "Joe Gaba Gaba", + hairColor = Color.Red, + eyeColor = Color.Green + } + + conn.Send(characterMessage); + } + + void OnCreateCharacter(NetworkConnection conn, CreateMMOCharacterMessage message) + { + // playerPrefab is the one assigned in the inspector in Network + // Manager but you can use different prefabs per race for example + GameObject gameobject = Instantiate(playerPrefab); + + // Apply data from the message however appropriate for your game + // Typically Player would be a component you write with syncvars or properties + Player player = gameobject.GetComponent(); + player.hairColor = message.hairColor; + player.eyeColor = message.eyeColor; + player.name = message.name; + player.race = message.race; + + // call this to use this gameobject as the primary controller NetworkServer.AddPlayerForConnection(conn, player); } } ``` -The function `NetworkServer.AddPlayerForConnection` does not have to be called from within `OnServerAddPlayer`. As long as the correct connection object and `playerControllerId` are passed in, it can be called after `OnServerAddPlayer` has returned. This allows asynchronous steps to happen in between, such as loading player data from a remote data source. - -The system automatically spawns the player game object passed to` NetworkServer.AddPlayerForConnection` on the server, so you don’t need to call `NetworkServer.Spawn` for the player. Once a player is ready, the active networked game objects (that is, game objects with an associated `NetworkIdentity`) in the Scene spawn on the player’s client. All networked game objects in the game are created on that client with their latest state, so they are in sync with the other participants of the game. - -You don’t need to use `playerPrefab` on the `NetworkManager` to create player game objects. You could use different methods of creating different players. - ## Ready State In addition to players, client connections also have a “ready” state. The host sends clients that are ready information about spawned game objects and state synchronization updates; clients which are not ready are not sent these updates. When a client initially connects to a server, it is not ready. While in this non-ready state, the client can do things that don’t require real-time interactions with the game state on the server, such as loading Scenes, allowing the player to choose an avatar, or fill in log-in boxes. Once a client has completed all its pre-game work, and all its Assets are loaded, it can call `ClientScene.Ready` to enter the “ready” state. The simple example above demonstrates implementation of ready states; because adding a player with `NetworkServer.AddPlayerForConnection` also puts the client into the ready state if it is not already in that state. diff --git a/doc/Guides/toc.yml b/doc/Guides/toc.yml index 5417d1786..04405bc33 100644 --- a/doc/Guides/toc.yml +++ b/doc/Guides/toc.yml @@ -8,8 +8,6 @@ href: ClientsServers.md - name: Authentication href: Authentication.md -- name: Custom Players - href: CustomPlayer.md - name: Conversion href: Conversion.md - name: Network Profiler