Project Configuration

Adjusting Game Properties 🔗

In order to configure your project, we provide a file! This allows you to change your project's behaviour.

All Studio projects have an auto-generated file, see below for the file structure.

Example Properties File 🔗

# DO NOT EDIT: this project ID is unique to your repository and should not be changed
projectId: 6546c318242da444451434bd

# This is a mandatory user-specified identifier that can be used to share products and data between games.
# If you wish to share data (including player stats, purchases, leaderboard rankings, and more) between multiple Studio projects, 
# you should sync this attribute. This field is internal, and is not visible within your game. 
namespaceId: MineplexStudio 

game:
  # a name given to your game
  name: MicroBattles 
  # The visibility of your game. Options: HIDDEN, PLAYTEST, PUBLIC
  visibility: PUBLIC 
  # A multiline description for your game
  description: ["§fBe the §eLast Team §fstanding", "§fThe §bGlass Barrier §fwill disappear after §c10 seconds"] 
  # The item to be displayed in the game explorer
  iconItem: "minecraft:beacon"
  # A category for your game
  category: "PvP"
  # Any tags you'd like to add to your game
  tags: [ "Team", "Strategy" ]
  # The display name of your game in the lobby menu
  displayName: "Micro Battles"
  # players whitelisted to test your game on staging
  playtestPlayerIds: ["b2cc0572-9634-4210-baa6-803d7cb4f511", "0c6b231a-1f12-49b6-a1fc-1a9279de277c"]
  # an icon url to show on the bedrock compass
  iconURL: "https://fastly.picsum.photos/id/21/200/200.jpg?hmac=a2iQ6UhOjpU6jn7QSsCpk1CiiKTxmW1R4UivDsv-n8o"
  # supported Minecraft platforms
  supportedPlatforms: ["JAVA", "BEDROCK"]

# matchaker configuration
matchmaker:
  # an allocation mode (See details below)
  allocationMode: DYNAMIC 
  # Only can be set when allocationMode is STATIC
  maxReplicas: 4 
  # The minimum players for an instance (server) to start up
  minPlayers: 2
  # The maximum amount of players an instance of your game holds
  maxPlayers: 16
  # Determines if players should be allowed to join an instance of your game that is already running
  allowPlayerBackfill: false
  # Determines if players should be allowed to bypass the max player count to join as spectators
  allowSpectatorMode: false

# any mineplex provided dependencies you'd like to add - requires Organization account
dependencies:
  libraries:
    - MYTHIC_MOBS
    - MODEL_ENGINE
    - MYTHIC_DUNGEONS
    - MYTHIC_CRUCIBLE
    - PROTOCOLLIB
    - LIBSDISGUISES
    - DECENTHOLOGRAMS

Matchmaking and Game Allocation 🔗

Allocation Modes 🔗

STATIC allocation 🔗

• Your game will be allocated as a set of stateful containers. You can specify an additional property for the maximum number of containers (maxInstanceCount) and we will automatically provision additional servers based on the actual player load over time, up to that maximum count.
• In a static mode, players can queue for a specific instance of your game. For example, Clans-1, Clans-2, and so on. Your code should not make any assumptions about the actual number of servers at any given time. If there are no players on Clans-2, we may deallocate that instance until someone re-queues for Clans-2, at which point the server will be re-allocated (with its state restored).
• We reserve the right to restart containers as needed, but will fire off an event to your game before doing so. For example, if we need to restart Clans-2 to apply a code update that you published, our orchestration server will give your game a grace period to shut down before it is automatically restarted. This will be very similar to a SIGTERM and SIGKILL lifecycle in a process -- the game gets a warning first, giving it a chance to gracefully handle a shutdown, and then it is forcefully shut down at some point in the future. Our systems will make a best-effort attempt to avoid restarting instances with active players, and we will work on exposing the grace period as a parameter to you. We are still figuring out the best way to handle this case, but want for you to plan in advance for it.

DYNAMIC allocation 🔗

• Your game will be allocated on-demand in response to matchmaking and queuing events. For example, if your game requires four players to begin, and eight players enter the queue, two instances of the game will be created automatically by our matchmaking and orchestration systems behind the scenes. These players are also transferred automatically once your game enters a healthy state as per our SDK lifecycle management.
• In a dynamic mode, players queue for your game mode itself, and are allocated to game instances as they become available. For example, players may queue for SSM and end up being assigned to any number of different servers, as per our orchestration logic.
• Your game must interact with our lifecycle SDK to indicate when it is safe or unsafe to shut down the game. This is usually between minigame iterations. Our systems make a best-effort attempt to keep the container alive, and may add more players during this time (it's like a game lobby window). However, in some cases (such as if insufficient players are in the game mode), the container may be shut down. Once again, we will deliver a shutdown event and a grace period in case you want to re-queue players for another mode or lobby before the container is killed. Otherwise, players are sent back to the Mineplex hub.

Backfill 🔗

Backfill allows queued players to join instances of your game that are already running (specifically, those that are in the IN_GAME state). For example, if there is an instance of your game that is currently in the IN_GAME state with two players, and there are four remaining slots, then the next four players to queue for the game mode will be backfilled into the existing game instance.

Backfill can be enabled and disabled via the allowPlayerBackfill property in the game-properties.yaml file.

Spectator Mode 🔗

Spectator mode allows players to join instances of your game that are already running, even if those games are full. Spectators can join a game even if it does not enable backfill and is in the IN_GAME state. Unlike backfill players, spectators are not automatically allocated whenever players queue for the game -- they must specifically request to join as spectators via a special command.

Spectator mode can be enabled and disabled via the allowSpectatorMode property in the game-properties.yaml file. When this property is not specified, it defaults to false.

When spectator mode is enabled, your game must safely handle cases when the number of players on the server exceeds the maximum player count specified in the matchmaking configuration. For example, you can kick or re-queue excess players at the end of a game cycle if your game cannot accommodate them in the next round.

Dependencies 🔗

Mineplex has partnered with a number of leading plugin authors to support unique and innovative game experiences within the Studio. These plugins can be enabled using the dependencies.libraries configuration property within the game-properties.yaml file.

Some of the values that are currently supported are:

• MYTHIC_MOBS: This plugin allows you to create custom mobs with unique abilities and behaviors.
• MODEL_ENGINE: This plugin allows you to create custom models for mobs, items, and blocks.
• MYTHIC_DUNGEONS: This plugin allows you to create custom dungeons with unique mobs, loot, and mechanics.
• MYTHIC_CRUCIBLE: This plugin allows you to create custom PvP arenas with unique mechanics and objectives.
• PROTOCOLLIB: This plugin allows you to intercept and modify network packets.
• LIBSDISGUISES: This plugin allows you to disguise entities.
• DECENTHOLOGRAMS: This plugin allows you to create custom holograms.

Game Explorer Configuration 🔗

Players can find your game from the Mineplex Lobby using the compass icon and navigation menu. In the game explorer menu, they are able to see a list of attributes that describe your game which can be configured in the game-properties.yaml file. These attributes include:

• game.displayName: (string) the name of your game as shown to players in the game explorer menu. Unlike the project name (in game.name, which is used internally), this name can contain spaces and special characters.
• game.visibility: (HIDDEN, PLAYTEST, or PUBLIC) determines if your game is visible to players in the staging game explorer menu. Most games that are actively being developed and iteratively released (they are not in an initial draft stage) should be set to PLAYTEST. This setting only impacts the staging environment, as all approved and published games are visible in production.
• game.description: (string[]) a brief description of your game, separated into lines.
• game.iconItem: (string) the item that represents your game in the game explorer menu. This should be a valid Minecraft item ID, such as minecraft:diamond_sword.
• game.iconURL: (string) a URL to an image that represents your game in the game explorer menu. This is only visible in Bedrock clients.
• game.category: (string) the category that your game falls under in the game explorer menu. Examples include Survival, PvP, and Parkour.
• game.tags: (string[]) a list of tags that describe your game. These can describe categories, but can also describe attributes of the game such as Team, Sandbox, and so on.
• game.playtestPlayerIds: (string[]) a list of player UUIDs that are allowed to playtest your game on the staging network. This is useful for sharing your game with a select group of players before it is published to the Mineplex network.

Specialized Tags 🔗

Below is a list of specialized tags that you can apply in your game-properties.yaml that can affect your game when published.

• Arcade - Your game will be shown and playable via the Mixed Arcade system. Note that there are additional requirements you must meet to use this tag that can be found here

Advanced Configuration and Overrides 🔗

There are a set of internal overrides that can be applied to your project by the Mineplex team. These unlock advanced or non-standard functionality, which is generally available, but not exposed in the game-properties.yaml file. We currently support:

• Persistent volumes
  • When this setting is enabled, a persistent network file system will be attached to each of your game servers. It will be consistent based on the game identifier (for example, Game-1 and Game-2 will have unique file stores, but the file system within each is persistent across server restarts).
  • The file system is always mounted at the /data directory.
  • This feature is only supported for games that use the STATIC allocation mode.
• Health check modifications
  • Changing the default health check wait time after server initialization. This may be useful if your games take a long time to start up, and you want to avoid the health check failing prematurely.
  • Changing the default health check interval. This may be useful if your game may be expected to ignore the Health SDK or not respond to it in a timely manner.

If you are interested in enabling these features, please reach out to us via a support request.