Preamble

The goal of this project is to create an alternate, Python-implementation to the official community server API, which is written in C#. This project can be considered production-ready.

Prerequisites

• Python 3.10 or later
• A running, whitelisted BattleBit Server (Version 2.1.2)

Usage

As a user of this API, there are two important things to know, Handlers and Commands. More on those in the following paragraphs. Basic examples on how to use this project can be found in /battlebit_community_server_api/example.

Handlers

Handlers are the users way of hooking themselves onto certain events that are happening. Such as "A player joins the server" and "A player sent a chat message".

For each event, the user can register their own handler with the ApiServer.register_handler method. This method takes an OpCodes value and any Callable.

IMPORTANT: Each handler has the signature async def handler(d: bytes) -> bytes. It receives the raw TCP message as an input and returns a TCP message.

Use TcpParsingService to parse the incoming data into the datamodel objects. Use OutgoingGameServerMessage to return data. Refer to the examples for further information.

Default Handlers

If there is no Handler registered for an OP-Code, the default Handler for that event is executed. The user can also use default Handlers in their own Handler, see example/SendingCommands.py.

Implementation status of default handlers

Event	Status	Behavior	Associated Parser (from TcpParingService)
HAIL		HAIL is accepted	parse_hail_message
PLAYER_CONNECTED		Event does not expect a response	parse_player_connected
PLAYER_DISCONNECTED		Event does not expect a response	parse_player_disconnected
ON_PLAYER_TYPED_MESSAGE		Allows message via RESPOND_PLAYER_MESSAGE	parse_on_player_typed_message
ON_PLAYER_KILLED_ANOTHER_PLAYER		Event does not expect a response	parse_on_player_killed_another_player
ON_PLAYER_JOINING		Official Stats are returned via SEND_PLAYER_STATS	parse_on_player_joining
SAVE_PLAYER_STATS		Event does not expect a response	parse_save_player_stats
ON_PLAYER_ASKING_TO_CHANGE_ROLE		Allows requested role change via SetRoleTo	parse_on_player_asking_to_change_role
ON_PLAYER_CHANGED_ROLE		Event does not expect a response	parse_on_player_changed_role
ON_PLAYER_JOINED_A_SQUAD		Event does not expect a response	parse_on_player_joined_a_squad
ON_PLAYER_LEFT_SQUAD		Event does not expect a response	parse_on_player_left_squad
ON_PLAYER_CHANGED_TEAM		Event does not expect a response	parse_on_player_changed_team
ON_PLAYER_REQUESTING_TO_SPAWN		Request is granted via SPAWN_PLAYER	parse_on_player_requesting_to_spawn
ON_PLAYER_REPORT		Event does not expect a response	parse_on_player_report
ON_PLAYER_SPAWN		Event does not expect a response	parse_on_player_spawn
ON_PLAYER_DIE		Event does not expect a response	parse_on_player_die
NOTIFY_NEW_MAP_ROTATION		Event does not expect a response	parse_notify_new_map_rotation
NOTIFY_NEW_GAME_MODE_ROTATION		Event does not expect a response	parse_notify_new_gamemode_rotation
NOTIFY_NEW_ROUND_STATE		Event does not expect a response	parse_new_round_state
ON_PLAYER_ASKING_TO_CHANGE_TEAM		Allows requested team change via SetTeamTo	parse_on_player_asking_to_change_team
GAME_TICK		Event does not expect a response	parse_game_tick
ON_PLAYER_GIVEN_UP		Event does not expect a response	parse_on_player_given_up
ON_PLAYER_REVIVED_ANOTHER		Event does not expect a response	parse_on_player_revived_another
ON_SQUAD_POINTS_CHANGED		Event does not expect a response	parse_on_squad_points_changed
NOTIFY_NEW_ROUND_ID		Event does not expect a response	parse_notify_new_round_id
LOG		Logs will be written to logger on DEBUG level	parse_log
ON_SQUAD_LEADER_CHANGED		Event does not expect a response	parse_on_squad_leader_changed
UPDATE_NEW_GAME_DATA		Event does not expect a response	parse_update_new_game_data
UPDATE_CONNECTED_PLAYERS		Event does not expect a response	parse_update_connected_players

Commands

While Handlers are triggered on an event and respond to the server, Commands can be executed at any point.

To execute an Command, pick a Command from the Command module (for example Command.SayToChat), use its initializer to prepare it, and then queue it for execution.

You can also build your own commands by using the Command base class.

To execute a command, use ApiServer.add_command_to_queue.

Predefined commands

Predefined OutgoingGameServerMessages

New in version 0.1.1

There are OutgoingGameServerMessages that have already been preconfigured with the correct OP-Code and accept typed arguments. Below is a list of the ones that are currently available.

The predefined OutgoingGameServerMessages can be imported from battlebit_community_server_api.helper.PredefinedOutgoingGameServerMessages.

Adding commands from outside

At some point you might want to queue Commands or OutgoingGameServerMessages from outside the API loop. You can find an example doing just that at example/SetNewRoomSettings.py.

Contributing

The current state of development does not yet allow for productive, cooperative contribution.

Licence

           DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
                   Version 2, December 2004

Copyright (C) 2023 David Rodenkirchen <davidr.develop@gmail.com>

Everyone is permitted to copy and distribute verbatim or modified
copies of this license document, and changing it is allowed as long
as the name is changed.

           DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
  TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

 0. You just DO WHAT THE FUCK YOU WANT TO.