Skip to content

About

Runtime implementation of Fall Guys Catapult protocol

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

55 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Catapult.Runtime.Protocol

Runtime implementation of Fall Guys Catapult protocol

Fall Guys uses Protobuf to communicate with servers over websockets. The only problem is that on the client side all protocol implementation is generated into a single large file that is hard to maintain. This project solves this problem by working with messages completely in the runtime

Installation

dotnet add package Catapult.Runtime.Protocol

Usage Examples

Tip

You can inspect raw protobuf bytes via Protobuf Decoder

Reading a message

using Catapult.Protocol;
using Catapult.Runtime.Protocol;
using Newtonsoft.Json;

RuntimeProtocol.Initialize(); //initialize messages

//sample of protobuf bytes that you get over websocket
var bytes = Convert.FromHexString("AAA9D2F902280A260A2465323631633832622D393537622D346435632D616631382D3935323961623334363961320A1CE2A9FCC201160A12093FFB295CC4BD644E118EE5C6A23654574310030A13AA9FF6D3020D0A0B08FCA6E7ACB4E5FE3E1005");

var msg = RuntimeProtocol.ReadMessage(bytes);

Console.WriteLine($"<-- {msg?.GetTypeName()}");
Console.WriteLine(JsonConvert.SerializeObject(msg, Formatting.Indented));

Output

<-- Result<AuthenticationResponse>
{
    "Body": { "UserId": "e261c82b-957b-4d5c-af18-9529ab3469a2" },
    "Error": null,
    "IsSuccess": true,
    "Headers": [
        { "RequestId": "5c29fb3f-bdc4-4e64-8ee5-c6a236545743", "Type": 3 },
        { "Utc": "2026-03-09T03:26:07.9353278" }
    ]
}

Writing a message

Note

CorrelationHeader and OperationHeader attached to the message in RuntimeProtocol.CreateMessage(), no need to attach them manually

using Catapult.Protocol;
using Catapult.Runtime.Protocol;
using Catapult.Services.Gateway.Protocol.Client;

RuntimeProtocol.Initialize(); //initialize messages

var bytes = RuntimeProtocol.CreateMessage(new Message<AuthenticationRequest>()
{
    Body = new()
    {
        Token = "...",
        ContentEtag = "102"
    }
});

Console.WriteLine(Convert.ToHexString(bytes));

Output

E2B4F6B4020E0A0C0A032E2E2E120331303220000A19E2ADEF78140A12099D97218CE3B2314E11BE7402A5881B8E690A1CE2A9FCC201160A12095561604C2D6F1941118E73F488236DE2791002

Handling messages

using Catapult.Protocol;
using Catapult.Runtime.Protocol;
using Catapult.Services.Gateway.Protocol.Client;

RuntimeProtocol.Initialize(); //initialize messages

//sample of protobuf bytes that you get over websocket
var bytes = Convert.FromHexString("AAA9D2F902280A260A2465323631633832622D393537622D346435632D616631382D3935323961623334363961320A1CE2A9FCC201160A12093FFB295CC4BD644E118EE5C6A23654574310030A13AA9FF6D3020D0A0B08FCA6E7ACB4E5FE3E1005");

var msg = RuntimeProtocol.ReadMessage(bytes);

Console.WriteLine($"<-- {msg?.GetTypeName()}");

switch (msg)
{
    case Result<AuthenticationResponse> authResp:
        Console.WriteLine($"We authenticated with account: {authResp.Body?.UserId}");
        Console.WriteLine($"Auth time (UTC): {authResp.GetHeader<TimestampHeader>()?.Utc}");
        break;
    default:
        throw new NotSupportedException();
}

Output

<-- Result<AuthenticationResponse>
We authenticated with account: e261c82b-957b-4d5c-af18-9529ab3469a2
Auth time (UTC): 3/9/2026 3:26:07 AM

Handling errors

using Catapult.Protocol;
using Catapult.Runtime.Protocol;
using Newtonsoft.Json;

RuntimeProtocol.Initialize(); //initialize messages

//sample of protobuf bytes that you get over websocket
var bytes = Convert.FromHexString("EAE6E80B270A25089003120A426164526571756573741A0A54657374206572726F72220808661204546573740A19E2ADEF78140A1209BDC26A242B6955451186669AA2B649851F0A1CE2A9FCC201160A1209E0BCF20E0202974E1183348EAADA9BBFCF1003");

var msg = RuntimeProtocol.ReadMessage(bytes);

Console.WriteLine($"<-- {msg?.GetTypeName()}");

if (msg is ErrorMessage err)
{
    Console.WriteLine($"Fall Guys returned error: {JsonConvert.SerializeObject(err, Formatting.Indented)}");
    return;
}

Console.WriteLine("No errors!");

Output

<-- ErrorMessage
Fall Guys returned error: {
    "Error": {
        "errorCode": 400,
        "ErrorString": "BadRequest",
        "Message": "Test error",
        "Details": { "ServerCode": 102, "Reason": "Test", "TechnicalMessage": null, "Inner": null }
    },
    "IsSuccess": false,
    "Headers": [
        { "ActivityId": "246ac2bd-692b-4555-8666-9aa2b649851f" },
        { "RequestId": "0ef2bce0-0202-4e97-8334-8eaada9bbfcf", "Type": 3 }
    ]
}

Obtaining protobuf models

You can obtain Protobuf models simply by dumping the game via Il2CppDumper. Dummy Assemblies contain all required to go attributes

To get a decompilation of models you can use IlSpy to decompile dummy dlls generated by Il2CppDumper into csharp source files.
To maintain a proper project design enable Use nested directories for namespaces in IlSpy settings before decompiling.

License

GNU GPLv3 Image

© Mediatonic Limited Fall Guys and all related characters and elements are trademarks of Mediatonic Limited

About

Runtime implementation of Fall Guys Catapult protocol

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages