Welcome to the LibreMatch Documentation

LibreMatch is a community-driven project that provides tools and APIs for accessing Age of Empires game data.

Getting Started - New here? Start with our beginner-friendly guides
Data Sources - Overview of all available data sources and APIs
WorldsEdgeLink API - Documentation for the Worlds Edge Link API
Age of Empires API - Official Age of Empires API documentation
LibreMatch Design - Architecture and design documentation

What is LibreMatch?

LibreMatch provides:

API Documentation - Comprehensive docs for various Age of Empires data sources
Open Source Tools - Libraries and tools for accessing game data
Community Resources - Guides and examples for building your own tools

Getting Help

Join the Libre:Match Discord for community support
Check the FAQ for common questions
Explore open source projects for working examples

API Reference - Constants & Enums

This page provides a quick reference for all IDs and constants used in the WorldsEdgeLink API.

Source: These values are extracted from the API responses of /community/leaderboard/GetAvailableLeaderboards and /game/automatch2/getAutomatchMap.

Leaderboards

ID	Name	Description
1	`SOLO_DM_RANKED`	1v1 Death Match
2	`TEAM_DM_RANKED`	Team Death Match (2v2, 3v3, 4v4)
3	`SOLO_RM_RANKED`	1v1 Random Map
4	`TEAM_RM_RANKED`	Team Random Map (2v2, 3v3, 4v4)
5	`SOLO_BR_RANKED`	Battle Royale (FFA)
13	`SOLO_EW_RANKED`	1v1 Empire Wars
14	`TEAM_EW_RANKED`	Team Empire Wars (2v2, 3v3, 4v4)

Match Types

ID	Name	Mode
2	1V1	Death Match
3	2V2	Death Match
4	3V3	Death Match
5	4V4	Death Match
6	1V1	Random Map
7	2V2	Random Map
8	3V3	Random Map
9	4V4	Random Map
10	FFA	Battle Royale
26	1V1	Empire Wars
27	2V2	Empire Wars
28	3V3	Empire Wars
29	4V4	Empire Wars
60	CUSTOM_DM_1v1	Custom Death Match 1v1
61	CUSTOM_DM_TEAM	Custom Death Match Team

Civilizations (Races)

ID	Name
0	Aztecs
1	Berbers
2	Britons
3	Bulgarians
4	Burmese
5	Byzantines
6	Celts
7	Chinese
8	Cumans
9	Ethiopians
10	Franks
11	Goths
12	Huns
13	Incas
14	Hindustanis
15	Italians
16	Japanese
17	Khmer
18	Koreans
19	Lithuanians
20	Magyars
21	Malay
22	Malians
23	Mayans
24	Mongols
25	Persians
26	Portuguese
27	Saracens
28	Slavs
29	Spanish
30	Tatars
31	Teutons
32	Turks
33	Vietnamese
34	Vikings
35	Burgundians
36	Sicilians
37	Poles
38	Bohemians
39	Bengalis
40	Dravidians
41	Gurjaras

Note: Civilization IDs may shift when new DLCs are released. See the Changelog for historical changes.

Leaderboard Regions

ID	Name
0	Europe
1	Middle East
2	Asia
3	North America
4	South America
5	Oceania
6	Africa
7	Unknown

Maps (Selection)

Common ranked maps:

ID	Filename	Map Name
1	AfricanClearing.rms	African Clearing
2	Arabia.rms	Arabia
3	Arena.rms	Arena
4	FourLakes.rms	Four Lakes
5	Islands.rms	Islands
6	nomad.rms	Nomad
7	Yucatan.rms	Yucatan
14	Black_Forest.rms	Black Forest
17	Fortress.rms	Fortress
20	Mediterranean.rms	Mediterranean
23	megarandom.rms2	Mega Random
26	Michi.rms	Michi
29	Nile Delta.rms	Nile Delta
36	Ghost_Lake.rms	Ghost Lake
37	goldenpit.rms2	Golden Pit
38	GoldenSwamp.rms	Golden Swamp
39	Kilimanjaro.rms	Kilimanjaro
40	valley.rms2	Valley
41	acropolis.rms2	Acropolis
43	Serengeti.rms	Serengeti

Note: Map IDs vary by match type (1v1, 2v2, etc.). The full list is available in the getAutomatchMap endpoint.

Game Titles

Value	Game
`age1`	Age of Empires: Definitive Edition
`age2`	Age of Empires II: Definitive Edition
`age3`	Age of Empires III: Definitive Edition
`age4`	Age of Empires IV

Platforms

Value	Platform
`PC_STEAM`	Steam
`PC_WINDOWS_STORE`	Microsoft Store / Xbox

Result Codes

Code	Message	Description
0	`SUCCESS`	Request successful
-1	`FAILED`	Generic failure
2	`INVALID_SESSION`	Session expired, re-authenticate

HTTP Status Codes

Code	Meaning	Action
200	OK	Request successful
429	Too Many Requests	Rate limited - back off and retry
403	Forbidden	Invalid or expired session

API	Limit	Recommendation
Community API	50 req/sec	Safe for most use cases
Game API	~200 req/min	Use 100 req/30 sec for safety

Getting Started

Welcome to the LibreMatch developer documentation! This section will help you get started with building applications using the Worlds Edge Link API for Age of Empires games.

What You Can Build

The Worlds Edge Link API enables you to create:

Lobby Browsers - Display and filter available game lobbies
Match Spectator Tools - View and follow ongoing games
Player Tracking - Monitor specific players’ activities
Community Tools - Custom integrations for your local gaming community
Statistics Dashboards - Aggregate and visualize game data

Choose Your Path

I Want to Build a Lobby Browser

Start here if you want to create a tool that displays game lobbies and matches.

→ Example: Building a Lobby Browser

This guide covers:

Quick start with the public Community API (no authentication)
Advanced features using the authenticated Game API
Code examples and best practices
Response parsing and data handling

I Have Questions

Check our comprehensive FAQ for quick answers to common questions.

→ Frequently Asked Questions

Topics covered:

General API questions
Authentication and setup
API usage and filtering
Development tips
Troubleshooting

Quick Links

API Endpoints

Endpoint Type	Authentication	Use Case	Documentation
Community API	None required	Public lobby listings	Quick Start Guide
Game API	Steam required	Ongoing matches, detailed data	Advanced Guide

Essential Resources

RLINK Documentation - Complete API reference
Libre:Match Discord - Community support and discussion

Open Source Projects

LibreMatch Organization - GitHub

librematch-collector - Polling, diffing, parsing and converting data from the Relic Link API for storing in Libre:Match Database
librematch-rlink_client - Relic Link API-Client generated from OpenAPI
librematch-steam_auth - Steam authentication proxy for use with Relic Link API
ageLANServer - Open source LAN server implementation with model definitions

Before You Begin

For Basic Lobby Browsers:

No special requirements - just make HTTP requests!
Recommended: 5-second polling interval with caching

For Advanced Features (Spectating, Match Data):

Steam account with the game purchased
Node.js or similar environment for authentication
Understanding of Steam authentication flow

Need Help?

Browse the FAQ for common questions
Check the example implementations
Join the community on Discord
Explore open source projects for working code

Contributing

Found something missing or incorrect? This documentation is community-maintained. Contributions are welcome to help fellow developers!

*Ready to start? Pick a guide above and begin building! *

Building a Lobby Browser for Age of Empires II: Definitive Edition

This guide covers how to interact with the Worlds Edge Link API to build custom lobby browsers and spectator tools for Age of Empires games.

Overview

The Worlds Edge Link API provides two main approaches for accessing lobby data:

Community API - Public, unauthenticated access to lobby listings
Game API - Authenticated access to ongoing matches and detailed game data

For simpler integration, you can also use the aoe2lobby.com WebSocket API which provides real-time updates without polling.

Quick Start: Community API

Basic Lobby Listing

For a simple lobby browser, use the community endpoint /advertisement/findAdvertisements:

GET https://aoe-api.worldsedgelink.com/community/advertisement/findAdvertisements?title=age2

Features:

No authentication required
Public lobby data only
Recommended polling interval: 5 seconds with client-side caching
No WebSocket/push notification support

This is sufficient for most lobby browsing use cases.

Advanced: Game API (Authenticated)

For accessing ongoing matches and spectator features, you’ll need to authenticate using Steam.

We provide a reference implementation written in Python that you may want to have a look at.

Prerequisites

Steam account with the game purchased
Node.js environment (examples use JavaScript)
’‘steam-user’’ npm package for Steam authentication

Authentication Flow

Step 1: Create Encrypted App Ticket

const SteamUser = require('steam-user');
const client = new SteamUser();

// Login to Steam first (with your credentials)
await client.logOn({...});

// Create encrypted app ticket
const APP_ID = 813780; // AoE2:DE
const eticket = await client.createEncryptedAppTicket(
    APP_ID, 
    Buffer.from("RLINK")  // Important: Include RLINK buffer
);

// Encode for API use
const auth = encodeURIComponent(
    eticket.encryptedAppTicket.toString('base64')
);

Important Notes:

Always include ’‘Buffer.from(“RLINK”)’’ as the second parameter
Don’t spam login attempts - Steam will rate limit and require verification codes
The auth string must be both Base64 and URI encoded

const url = `https://aoe-api.worldsedgelink.com/game/login/platformlogin?`
    + `accountType=STEAM`
    + `&activeMatchId=-1`
    + `&alias=${alias}`
    + `&appID=${APP_ID}`
    + `&auth=${auth}`  // Your encoded ticket from Step 1
    + `&callNum=0`
    + `&clientLibVersion=190`  // Update as game updates
    + `&country=US`
    + `&installationType=windows`
    + `&language=en`
    + `&macAddress=DE-AD-D0-0D-00-00`  // Can be any value
    + `&majorVersion=4.0.0`
    + `&minorVersion=0`
    + `&platformUserID=${steamID}`
    + `&timeoutOverride=0`
    + `&title=age2`;

const response = await axios.post(url);
const sessionId = response.data.sessionID; // Save this!

Key Parameters:

’‘clientLibVersion’’ - Currently 190+ (changes with game updates)
’‘macAddress’’ - Can be any valid format
’‘auth’’ - Your encoded ticket from Step 1
Returns a ’‘sessionID’’ needed for subsequent requests

Getting Game Build Version

The ’‘appBinaryChecksum’’ parameter requires the current game build version. You can obtain this programmatically:

const getBuildVersion = async (appId) => {
    const rss = await fetch(
        `https://store.steampowered.com/feeds/news/app/${appId}/`
    );
    const parser = new XMLParser();
    const feed = parser.parse(await rss.text());
    
    let lastUpdateTitle = feed?.rss?.channel?.item
        ?.map(e => e.title)
        .find(e => e.match(/(update.[0-9]+)/gi));
        
    return parseInt(
        lastUpdateTitle.slice(
            lastUpdateTitle.search(/update/gi) + "update".length
        )
    );
}

Alternatively, check the bottom-left corner when launching the game.

Finding Observable Matches

Once authenticated, query ongoing games:

const url = `https://aoe-api.worldsedgelink.com/game/advertisement/findObservableAdvertisements?`
    + `appBinaryChecksum=${gameVersion}`
    + `&callNum=0`
    + `&count=50`
    + `&dataChecksum=0`
    + `&desc=1`
    + `&matchType_id=0`
    + `&modName=INVALID`
    + `&modDLLChecksum=0`
    + `&modDLLFile=INVALID`
    + `&modVersion=INVALID`
    + `&start=0`
    + `&sortOrder=1`
    + `&versionFlags=56950784`
    + `&sessionID=${sessionId}`
    + `&connect_id=${sessionId}`;

const response = await axios.get(url);

Filtering Options

By Player Profiles

&profile_ids=[123456,789012]

Filter matches to only show games with specific player profile IDs.

By Numeric Tags

&numericTagNames=["HasPassword"]
&numericTagValues=[0]

Common tags include:

’‘HasPassword’’ - Filter by password-protected status
Other tags available but not fully documented

Response Format

Warning: The Game API returns responses in an obscured array format that is not user-friendly.

// Example response structure
[
    someMetadata,
    [  // Array of matches
        [lobbyId, platformSessionId, ...otherFields],
        [lobbyId, platformSessionId, ...otherFields],
        // etc.
    ]
]

Parsing Help:

Responses are positional arrays, not named objects
Element positions are stable across API versions
See this reference implementation for field mappings
The second element of the response contains the array of advertisements
Each advertisement follows the order: lobby ID, platform session ID, followed by other fields

Alternative: WebSocket API

For simpler integration, consider using the aoe2lobby.com WebSocket API:

Real-time updates (no polling needed)
Clean, documented data format
Provides schema information on connection
Free to use for community projects
Live for 8+ months with proven reliability

Connection

WebSocket URL: ``` wss://data.aoe2lobby.com/ws/

The API supports subscribing to different data feeds by sending JSON subscription messages.

### Subscription Examples
**Subscribe to spectate matches:**
```json

{"action":"subscribe","type":"matches","context":"spectate"}

Subscribe to lobby matches:

{ "action": "subscribe", "type": "matches", "context": "lobby" }

Subscribe to specific Elo types:

{
    "action": "subscribe",
    "type": "elotypes",
    "context": "lobby",
    "ids": ["1223", "3", "4"]
}

Subscribe to specific players:

{
    "action": "subscribe",
    "type": "players",
    "context": "lobby",
    "ids": ["3920944"]
}

Player status updates include current status, match ID, and Steam lobby ID:

{
    "player_status": {
        "19501096": {
            "status": "lobby",
            "matchid": "412015195",
            "steam_lobbyid": "109775244730862406"
        }
    }
}

Resources

Instructions: aoe2lobby.com chat section
Discord support: aoe2lobby Discord

Best Practices

Read the Age of Empires API Usage Guidelines!

Rate Limiting

Server implements rate limiting - don’t spam requests
Use reasonable polling intervals (5+ seconds)
Cache results when possible
Consider batch operations for multiple profile lookups

Version Management

’‘clientLibVersion’’ changes with game updates
Can be found by inspecting network traffic with Wireshark
Hardcoded in the game binary/PE file
Current version as of late 2024: 190+

Authentication

Session IDs persist for some time
Avoid repeated Steam logins (triggers verification)
Use a dedicated Steam account for service authentication
Consider running auth service separately from main app

Additional Resources

Documentation & Projects

Lib:reMatch Steam-Auth: Reference implementation (Python)
Lib:reMatch OAPI-RLINK-Client: Generated example python client incl. openapi.yaml
Lib:reMatch Wiki: RLINK documentation
ageLANServer: Open source server implementation with model definitions
aoe2lobby.com: WebSocket API for easier integration
aoe2recs.com: Example browser implementation

Community Support

AOE API developer channels
Libre:Match Discord
Various open source projects with working examples

Contributing

This documentation is community-maintained. If you discover new endpoints, parameters, or corrections, please contribute back to help other developers!

*Last updated: December 2025 *

*Based on community research and shared knowledge *

FAQ

General Questions

Q: Is there a WebSocket API instead of polling?

A: The official Worlds Edge Link API does not provide WebSocket/push notifications. You must poll the endpoints. However, third-party services like aoe2lobby.com offer WebSocket APIs that aggregate this data. Some developers have proposed creating a service that polls and converts to push notifications.

Q: Should I use an existing lobby browser?

A: If you just need basic functionality, existing browsers work well. However, building your own is worthwhile for:

Custom features for specific communities
Localization and personalization
Learning and hobby projects
Integration with other tools

Q: Do I need authentication for a basic lobby browser?

A: No! The [GET] /community/advertisement/findAdvertisements endpoint on the Community API provides public lobby data without authentication. Authentication is only needed for:

Viewing ongoing ranked games
Spectator features
Detailed match information
Player-specific filtering

Authentication & Setup

Q: Steam blocked me from logging in, what do I do?

A: Too many login attempts trigger Steam’s security. Wait some time and it will unblock automatically. To avoid this:

Don’t spam login attempts while testing
Cache your session ID and reuse it
Use a dedicated account for your service
Implement proper retry logic with backoff

Q: Why do I need Buffer.from(“RLINK”)?

A: This is a required parameter for the encrypted app ticket to work with the Worlds Edge Link API. The ticket must be created specifically for RLINK authentication, not just for the game itself.

Q: How do I find the current clientLibVersion?

A: Several methods:

Use Wireshark to capture game network traffic
Search the game binary/PE file (hardcoded)
Check community resources (currently 190+)
Parse Steam RSS feeds for update announcements

Note: This value changes with game updates, so plan for updates.

Q: Where do I get the game build version (appBinaryChecksum)?

A: Three options:

Bottom-left corner when launching the game
Parse Steam RSS feeds programmatically (see code example above)
Check community resources after updates

API Usage

Q: Why are the API responses such a horrible structure?

A: The Game API uses an internal format that returns positional arrays instead of named JSON objects. This is how the game client expects data. The Community API returns cleaner JSON. For Game API responses:

Positions are stable (consistent across versions)
Use reference implementations to understand field mappings
Consider using third-party APIs for cleaner data

Q: Can I filter results to specific players?

A: Yes! Although not officially documented:

Use ’‘profile_ids=[id1,id2]’’ parameter
Use ’‘numericTagNames’’ and ’‘numericTagValues’’ for other filters
Filtering happens server-side for profile IDs
Some filtering (like game type) happens client-side in the official game

Q: Are there rate limits?

A: Yes, the server implements rate limiting. Best practices:

Poll at reasonable intervals (5+ seconds)
Implement client-side caching
Batch requests when possible
Monitor for rate limit responses

Q: Can I show ongoing ranked games?

A: Yes, but it requires the authenticated Game API for the [GET/POST] /game/advertisement/findObservableAdvertisements endpoint. The Community API only shows lobbies waiting for players, not matches in progress.

Development

Q: What should I use for macAddress?

A: You can use any valid MAC address format (e.g., ’‘DE-AD-D0-0D-00-00’’). The API doesn’t validate this strictly.

Q: Is there example code I can reference?

A: Yes! Check these open source projects:

ageLANServer (Go) - Complete server implementation with model definitions
Various community tools on GitHub
Code snippets shared in developer communities

Q: Is it legal to use these APIs?

A: The Community API is public and intended for community use. For the authenticated Game API:

Read the Age of Empires API Usage Guidelines
You must own the game on Steam
Don’t abuse the API or spam requests
Don’t create malicious tools (fake lobbies, spam, etc.)
Respect rate limits and terms of service

Q: Should I use aoe2lobby.com’s API instead?

A: Consider it if you want:

Real-time WebSocket updates (no polling)
Cleaner data format
Less maintenance (they handle game updates)
Quick integration

Build your own if you need:

Complete control over data and features
Custom filtering or processing
Independence from third-party services
Learning experience

Troubleshooting

Q: I’m not getting a session ID, what’s wrong?

A: Common issues:

Missing ’‘Buffer.from(“RLINK”)’’ in ticket creation
Incorrect Base64 and URI encoding of the auth parameter (the encoding must be combination of encodeURI(base64(encoding)))
Outdated ’‘clientLibVersion’’
Invalid or expired Steam ticket
Check all required parameters are present

Q: How do I parse the array response?

A: The response structure is:

First element: metadata
Second element: array of matches
Each match: array starting with [lobbyId, platformSessionId, …]

See the ageLANServer repository for complete field mappings in the ’‘advertisement.go’’ model.

Q: Do I need a separate authentication service?

A: It’s recommended to separate authentication from your main app:

Keeps Steam credentials isolated
Can run on a dedicated account
Easier to manage session refresh logic
Can serve multiple clients

Contributing

This documentation is community-maintained. If you discover new endpoints, parameters, or corrections, please contribute back to help other developers!

*Last updated: December 2025 *

*Based on community research and shared knowledge *

LibreMatch Project

LibreMatch is a community-driven project providing tools and APIs for accessing Age of Empires game data.

Documentation Sections

Data Sources

Data Sources Overview - All available APIs and data sources

Design Documentation

Architecture and design documents for LibreMatch components:

Architecture - System architecture overview
Backend - Backend services design
Collector - Data collection service
Persistence - Data storage and caching
Matchmaking - Matchmaking system design
Localization - Multi-language support
Proxy - Proxy service design
Statistics - Statistics and analytics
Teams - Team management
Tournaments - Tournament system

Project Planning

Roadmap - Project roadmap and milestones

Open Source Repositories

librematch-collector - Data collection from Relic Link API
librematch-rlink_client - OpenAPI client for RLINK
librematch-steam_auth - Steam authentication proxy
librematch-database - Database schema and migrations

Roadmap

PoC Script
1. play a bit around with it how to get data from different endpoints
2. adopt it to any changes on the API and the different endpoints
3. create test script out of it that tests the availability of different endpoints, which parameters are optional and saves the responses together with the requests for easier OpenAPI file generation
4. analyse the responses and map them to fields and document it
Data collection & Database
1. based on our findings from the PoC Script we can start thinking about database layout and implement a tool for data collection
2. we should divide our effort into a smaller working group that starts with thinking about a possible architecture
3. i think it makes sense to automate as much as possible, e.g. logging the endpoints/requests the games use together with the responses, automatically create an openapi file from it, generate a client from it for the data collector and pull in this generated client as a library for the data collector itself, so it’s easier to update
4. sufficient error handling will be pretty important here as the API is relatively instable and as you might see from the initial response, it’s basically one huge JSON array with only the values, sometimes completely empty arrays at positions, the order of these things might also changes by chance without any warning
Backend
1. in parallel we can draft a possible backend solution
2. for most information a basic REST-API will be sufficient, but for other things Pub/Sub and Websockets will be nice (e.g. subscribing to the matches of a player and get updates in real-time)
3. also it would be nice to have a login endpoint for e.g. tournament organizers, so they can hide the results of matches of certain relic-link ids for a limited amount of time to avoid spoilers
Frontend(s)
1. imho frontends should be not part of the work of this group
2. frontends can be implemented by anyone that likes to use our backend
3. we can ask someone or maybe we know already some people that can create nice ones and cooperate with these people closely
4. like this we divide our effort and fix on the purpose of having a stable API for the community while other people are able to concentrate on their frontend efforts

Data Sources

This section documents all available data sources that LibreMatch uses to collect Age of Empires game data.

WorldsEdgeLink API (RLINK)

The primary source for game data is the WorldsEdgeLink API.

WorldsEdgeLink Introduction - Overview and general information
API Changelog - History of API changes

Endpoints

API	Authentication	Description
Community API	None	Public lobby listings, leaderboards, achievements. Most data should be fetched from here.
Game API	Steam required	Ongoing matches, detailed data. Use sparingly for essential features only.

Other Data Sources

Age of Empires Official API - Official API at ageofempires.com
Steam Web API - Steam platform integration

Miscellaneous

gRPC API (CA:DE) - gRPC-based API for Command & Conquer: Definitive Edition

API Changelog

This section tracks changes to the WorldsEdgeLink API, particularly those that affect ID mappings.

Mapping Versions

Version	Description	Date
1	Pre-Return of Rome	Before 2023-05
2	Return of Rome DLC	2023-05-13
3	June Cumulative Update	2023-06
4	Mountain Royals DLC	2023-10-31
5	Current mappings	2024-04-30+

Breaking Changes

When new civilizations are added via DLC, civilization IDs often shift. Always use the Constants & Enums Reference for current values.

Change History

2023-04-30: AoE2DE EW changes

Copied from ~Jp (World’s Edge Server Engineer):

The AoE2 Empire Wars 1v1 ladder will temporarily be replaced by a new ladder for seeding the RBW tournament.

The new match type IDs will be 122 (crossplay/cross-input) and 123 (console).

The leaderboard IDs, respectively, will be 27 and 28.

We’ll be monitoring the top 100 there more closely for cheating / manipulation.

If you notice someone cheating or manipulating their position, please do let us know so we can take action, as well as improving our detection methods.

Attached you’ll find the new mappings.

Mappings

The values contain the following mappings:

Version 1 is pre-RoR.
Version 2 is RoR.
Version 3 is the June CU.
Version 4 went live on 2023-10-31.
Version 5 are the values from 2024-04-30 onwards.

Civ IDs

I updated civ mappings to use -1 as a missing entry, instead of “-1”.

2023-05-13: AoE2DE RoR DLC changes

Copied from ~Jp (World’s Edge Server Engineer):

Hey everyone!

With RoR we’re making some changes that affect the APIs regarding lobbies, spectating and match history. The changes are mainly pertaining to the options string, civ IDs, match type IDs and map IDs.

I’ve decided to make a mapping to allow you to more easily update your resources. This mapping is constructed in the following way:

<Mapping Type>.json
{
  "Object Name": {
    "1": <ID in Dynasties of India>,
    "2": <ID in RoR>,
    "3+": <Reserved for future updates>
  },
<More Objects>
}

Mappings

Civ IDs

We’ve added the Romans before Saracens and incremented all Civ IDs of Saracens and above by 1.

Map IDs

Map IDs now map to loc string IDs, rather than an enum.
Some maps do not have loc string IDs yet and will appear as -2. (This is a known issue we are working on.)

Options String

We’ve removed key 2, leading to all keys being decremented by one.
We’ve also added a new option, 97, which will distinguish, in custom lobbies, whether people are playing RoR or AoE2.97: 1 means RoR, 97: 2 means AoE2.

Match Type IDs

We’ve added match type IDs 120 and 121, which are ranked RoR 1v1 and Team respectively.

2023-10-23: AoE2DE Mountain Royals DLC changes

Breaking Changes

With Armenians and Georgians added, all civilization IDs shifted.

Copied from ~Jp (World’s Edge Server Engineer):

Hey @everyone,

Here are the new mappings that will be going live with The Mountain Royals DLC.

Mappings

Recap

Here is a recap of what has changed and what hasn’t since the release of the Return of Rome DLC:

The Options string and Match Types have not changed.
Mapping #3 is the mapping for the June CU up until now.
It has the fixed map IDs in it (-2 -> fixed map ID).
Mapping #4 is the mapping for the current PUP and will be going live on the 31st with The Mountain Royals DLC.

This has the updated civilization IDs in it.

Design Documentation

Architecture and design documents for LibreMatch components.

Components

Architecture - System architecture overview
Backend - Backend services
Collector - Data collection service
Persistence - Data storage
Matchmaking - Matchmaking system
Proxy - Proxy service
Statistics - Statistics and analytics
Teams - Team management
Tournaments - Tournament system
Localization - Multi-language support

Architecture (Overview)

Example (Bright Sky)

Bright Sky pulls weather data from DWD and implements a JSON-API on top of it for its users. Their architecture looks like on the image on the right side. It’s some kind of the same what we also want to achieve.

This is taken from the Official repository:

The brightsky worker, which leverages the logic contained in the brightsky Python package to retrieve weather records from the DWD server, parse them, and store them in a database. It will periodically poll the DWD servers for new data.
The brightsky web server (API), which serves as gate to our database and processes all queries for weather records coming from the outside world.
A PostgreSQL database consisting of two relevant tables:

sources contains information on the locations for which we hold weather records, and
weather contains the history of actual meteorological measurements (or forecasts) for these locations.

A Redis server, which is used as the backend of the worker’s task queue.

LibreMatch

Basically, we should poll the Relic Link API endpoints for all data every so many seconds (this time is our minimum latency for our whole system). So the time frame in which we see certain information (Match infos, wins of games) and could deliver information to our API.

Then we parse the results into a data structure of ourselves to make error handling easier and also deal with types of data and not handle everything as a huge JSON-Array that is being exposed by the Relic Link API. This data we send to the database, which is our persistence layer. From our persistence layer, we are able to request data for our endpoints that we expose to the users. Some endpoints may require a Pub/Sub API (e.g. live updates for match information), some are fine with the usual REST-API approach.

Backend

Backend services design documentation.

Requirements

User Stories

Some things may be out of scope, we can still collect them here, to have an overview and include some of them in the design process.

User stands for the user of the LibreMatch API.

As a/an	I want to…	So that..
user	have a stable API	I can rely on it
user	request win data of the games	I can easily determine the outcome of a match
statistician	request database dumps for a time period	I can easily analyse a big amount of data without firing thousands of requests
authenticated tournament organizer	delay matches showing up for a limited amount of time	I can take care that people are not being spoiled
user	be able to get live updates about ongoing games	I can update my e.g. overlay immediately when a match starts
user	be able to log in with my Steam account	I can create lobbies from outside the game
user	be able to query for matches of a player since a timestamp	I can update a list of matches of a certain user more easily
user	be able to quickly start using the API	I am not spending much time reading the documentation or spend time implementing a client to use it
user	be able to get all matches by a player from different games at once	I don’t need to make several requests
user	be notified of match state updates of all matches or a subset	I don’t have to keep polling for updates and deriving state updates myself
user	get notified when changes are made to a lobby	I can update my lobby tables and reduce the amount of requests
recorded matches analyser	get notified when a new replay becomes available (e.g. in a leaderboard/from a player)	I can download and parse it in a timely fashion
user	embed a player report function in my page	people can report suspicious activity (e.g. spoofing) to the official franchise
user	be flexible in the usage of the API	I can take different approaches to find solutions to my problems
user	not over boarded with complexity to use the API	I can start out right away without reading much documentation (reasonable defaults)
user	be able to query match history for a player by either steam ID or another unique ID	can use the information for calculating statistics, building user facing APIs (eg. !match), build more complicated applications on top of the API
user	be able to query information on open/ongoing lobbies	can use the information for creating rich presence plugins
user	be able to query commonly used api strings (for maps, civs, etc.)	can map enum values for maps, civs that are returned by the usual API to names (the api could provide multiple localisations depending on a parameter)
user	be able to access typescript type interfaces for api responses	can easily incorporate the API in typescript applications
user	be able to query the data of a match that is being cast by a caster	can use it creating a bot to easily modify a casters’ stream title with one-click
user	be able to query the data of a match that is being cast by a caster	can compile a list of matches cast by a caster during one stream

Authentication

Sometimes resources will need authorization to be accessed by privileged community members. Such members could be tournament organizers and admins that want to set up a schedule within the backend to delay the access to certain player information for a limited amount of time. This could be needed during tournaments, so people aren’t able to find out results of matches before they are officially concluded (e.g. in case of casting recorded games) and spoil other people with the results.

The Relic Link ID aka RLINK_ID is a unique identifier for every player on the Relic Link platform, no matter if the person bought a game on Steam or Microsoft Store.

Authentication for a player on the Steam platform could be achieved by utilizing web browser based authentication with Steam OpenID.

OpenAPI

Documentation Generation

FastAPI will take care of generating the documentation page. We can choose from different UIs:

** ReDoc **
with a CLI that lints our OpenAPI spec
** SwaggerUI **

ReDoc has premium services and we need to check if although it looks more beautiful it’s worth to opt in to their free stage or if SwaggerUI is enough.

API first principle

We follow the API first principle. Meaning that we define our API first, before generating the backend stub and coding its implementation.

Our OpenAPI spec acts like a single source of truth (SSOT). Test cases are generated from the OpenAPI spec and the backend implementation needs to adhere to them.

Our design follows a few different design guidelines:

Deviations from Guidelines

We don’t use kebab case and snake case instead as the dash can easily introduce bugs as it can be interpreted as a minus sign.
We might want to use CalVer (Read github notes)

Assigning Scopes

https://opensource.zalando.com/restful-api-guidelines/#105

Pub/Sub-API

Some information for players might want to be constantly queried by the users of our API, for example match information. This information we should supply via an endpoint that can be subscribed to and communicates via a Websocket.

Collector

Data collection service for fetching game data from APIs.

Polling - Polling strategy
Parsing - Data parsing
Queue - Job queue system

Polling

The polling stage checks for updated data frequently. huey as a task scheduler/queue takes over triggering our polling jobs. Data queried from the authenticated endpoints get a separate job. These endpoints need special treatment, as in only query what’s essential.

Parsing

The parsing stages does the decoding/decompression, normalization and prioritization.

decoding/decompression
Some data, especially in ‘slotinfo’, is base64 encoded and further compressed with zlib.
normalization
The data format is ‘json-like’, but only contains arrays. Probably for bandwidth reasons.
We need to transfer the data in our own schema.
prioritization
Some data is the foundation for real-time information that we deliver to users of our API (state changes of lobbies, e.g. ongoing matches, and leaderboard rankings).
This data should fill ‘sorted sets’ or the Pub/Sub-Message bus from Redis.
conversion
For the localization data, we need to query data from the Relic Link API and convert it to the FTL (Fluent Translation) file format.

Queue

Matchmaking

Idea

Together with ncZone Eru and others
Role model maybe https://w3champions.com/
queue up on a website or with a discord bot command like !queue 1v1 DM Arabia
implement a platform-agnostic matchmaking basically
own custom rating (based on glicko2, probably)
own ladder system

Architecture

Client-Server (non-monolithic/microservices)(?)

Frontend

Basically: Frontend <—> REST-API (CRUD) <—> Matchmaking Library

Backend

Registration with aoe2-Profile-ID

e.g. !register <aoe2 profile id> – register the given account with the discord name
then you are asked by Direct Message to create a lobby with special randomly generated settings
the created lobby and the options are then checked by the bot and the mapping to the account is done internally
good thing is that the register endpoint can theoretically be queried from the outside with all kinds of stuff (should be platform-agnostic, whether it’s from openage or from voobly, from a discord bot, a web-app or anything else)

Persistence

basic PG stuff I guess for the user information
maybe a fast in-memory database for anything temporary that is only needed during the actual matchmaking process

UX

if it is less likely that you will find a match in the next 2-3 minutes, it will recommend you better settings to find a faster match
people should see how many players queue in the different settings
they should be free to queue at a setting they chose to find a match

they should be able to play what they want
if there are no players in that settings, we give feedback and recommend them settings how they would find a faster match
like having dynamically pop up an Arabia 1v1 queue because there are like 25 people queuing right now
1. could click on it and jump into the queue
2. if there is another queue for Socotra, and you have Socotra in your settings as a “beloved map”,
  - and there are 7 people in it, you could feel free to pull that into your personal queue as well and check if one or both queues gives you a game and so on

Recorded games upload and analysation

could even reward special plays analysed from the recorded game

we might want to reimplement/contribute to a recorded game parser in Rust ( https://github.com/SiegeEngineers/genie-rs/tree/default/crates/genie-rec )

could get the recorded games from official API

Requirements

User Stories

Some things may be out of scope, we can still collect them here, to have an overview and include some of them in the design process.

User stands for the user of the LibreMatch Matchmaking API.

As a/an	I want to…	So that..

Flow

Before the game

Persons can register for the matchmaking, becoming Users of our service
Users can connect their aoe2-profile with their account
Users can adjust their personal preferences regarding maps, ladders etc. in the settings.
Users can queue up for their settings or join a queue they see are the most people in, other recommendations
Users get informed of their match in their client with a pop-up, switching to the settings of the match
A Host is being decided randomly of all participating players.
Else, Users can set their preference in the settings if they like to be hosted more often.
Hosts create the game lobbies (until, we haven’t found a way to automate that)
Lobby settings get verified as much as possible via aoe2.net matches API endpoint
Match starts

After the game

get basic game information/result from aoe2.net
download, parse and analyse recorded games
use results if recs are unavailable

results when both players pick no team still show both winning, so recs would be best (aoe2.net)

create rating change

with the recs analysation, we could even calculate a more precise rating change depending on how the game played out
like a player that was dead in minute 13 and just stayed in the game until 1h25 because the person had a vill hidden in the corner should probably not get so much rating change as someone that was carrying all the people the whole game (just as an idea)

Rating

Glicko2
Discussion: different Ratings and influence on Matchmaking?

1vs1 Rating (RM/DM/EW), TG-Rating (RM/DM/EW), Arabia Rating?
or rather just a 1v1 and TG-Rating?
another possibility:
1. open/closed/hybrid-rating
2. three categories weighted
3. hybrid: megarandom, water, other ame modes
4. open could be arabia
5. closed something like black forest, arena, michi
6. if someone doesn’t care and wants to play open: !queue open 1v1,2v2
pair Rating systems:
1. someone who is super strong on Arabia should be also usable on Black Forest
2. Similarly, islands, whoever can do Archer Micro won’t go down completely.
3. If you consider them completely separately, you also run the risk that a player has too few games on individual ladders for decisive ratings.
4. it’s like core rating + open rating and both have to adjust a bit after one game.
5. or core rating + open rating + 1v1 Rating e.g. and then you can even weight them
6. something like core rating counts 50% of the overall rating, open rating 20%, 1v1 rating 30%
7. core rating can be also including the starting rating from another ladder/from another rating system with a factor to include it into the core rating for migrating from other platforms (something like this is existing already on ncZone)

AoE2DE currently does it like that.

Lobbies

Lobby creation (hacky)

Problem: How can we create custom lobbies in an automated way from outside the game? And who does it? How to make that as easy as possible?
this might be a bit reverse engineering and an external tool, but I assume not impossible (other ideas how to interface with the game are welcome)

this GPLv3-fork of the AoE2DE SDK (C++) might be helpful?
or a custom python script that reads the game?
autohotkey script?
check if possible: what about reversing the API endpoint on their backend and sending a request for opening a lobby in the name of any user that matched?
can the user itself join via a link?
is the lobby kept open automatically? or do we need to simulate some user activity in the lobby until everyone joined?

theoretically could be done later if the UX is nice and easy also without
lobby id once created should be distributed to the participants as a direct link aoe2de:\/\/0/89697553 people can just click

Drafting

Drawing civs and maps

like nc Zone
could be a feature which is supported like the random thing on DE if people opt-in to that
should be relatively easily possible
can be combined with the game analysation and we could get some player data, like how good is a player with a certain civ, is he drushing often etc. we could create teams based on the actual game skills players have
have an archer player and a cav player in each team, someone that usually drushes etc.

Ladders

Alternative Ladders

own ladder for everything we want
DM ladder, CBA ladder, Arena ladder, Arabia ladder
open and closed maps or even for a single frequently played map
arabia rank would get possible for example with special seeding for arabia only tournaments etc.

Persistence

Data storage and caching layer.

Controller
Cache - Caching (Redis)
Database - Database (Postgres)

Controller

Cache

Redis

Redis

Database

Postgres

Postgres

Extensions

visualise long-running requests and DB load we should use some statistics extension for Postgres

Database migration

We version control our database schema with a lightweight, framework-agnostic database migration tool called dbmate.

The database schema and migrations are open-source and can be found here. This repository acts like a single source of truth (SSOT) for the DB schema.

Partitioning

Replication

Notes

https://sqlfordevs.com/multiple-aggregates-in-one-query

Proxy

Information
Flowcharts

Information

The proxy forwards our requests and takes over authentication.

For the authenticated endpoints we should keep in mind:

use a separate Steam account (or maybe even this Xbox stuff with a subscription for all 4 games for that (cheaper?))
generally limit our access to the auth endpoints to a minimum (only what is really needed)

even rate-limit our requests

mimic in-game requests as close as possible

We will need a running instance of a Steam Client for each game. To circumvent limitations (as only holding one login to steam per account on a certain moment in time is needed) we use a proxy to forward our requests on behalf of a certain session.

Usage

Base URL: https://rlink.api.tools.uber.space/relic

You need to get an API_KEY for the proxy from the team members.

Then you can make calls to the proxy e.g. for endpoint /game/news/getNews call:

https://proxy.api.tools.uber.space/relic/game/news/getNews

You need to supply a header with the API_KEY e.g. API_KEY=...

All query parameters that you add to the request will be forwarded to the Relic Link API on your behalf.

Insomnia

Insomnia is a API design platform.

We have created some to use with their client.

Flowcharts

Startup

Authentication & Sessions

Steam Client

Relic Session

Update Session loop

Forwarding Requests & Responses

Statistics

Statistics and analytics documentation.

Teams

Team management documentation.

Tournaments

Design

Requirements

User Stories

Some things may be out of scope, we can still collect them here, to have an overview and include some of them in the design process.

User stands for the user of the LibreMatch Tournament API.

Admin stands for a verified and authenticated user (e.g. tournament organizer) of the LibreMatch Tournament API that is therefore eligible and authorised to use CRUD on some resources.

As a/an	I want to…	So that..
user	have a stable API	I can rely on it
user	request win data of the games	I can easily determine the outcome of a tournament match
admin	delay matches showing up for a limited amount of time	I can take care that people are not being spoiled

Additional Tooling

Architecture

Notes

https://help.start.gg/en/articles/1465676-rest-api-access-legacy-old

https://api.smash.gg/tournament/rising-empires-weeklies-10

Seeding Ideas

https://web.archive.org/web/20221130121235/https://www.aoezone.net/threads/simulated-ladder-seeding.185565/

Localization

To have our responses in different languages, we want to use Project Fluent (Python) as a framework in the backend.

This would imply, that we convert the official translations into ftl files.

l10n/
  de/
    main.ftl
  en-US/
    main.ftl

The conversion could be done in the Collector and then our Persistence Controller writes the data to our file system. For reading, writing and transforming Fluent files, there is the Fluent Syntax library.

Python Fluent code would look like this:

# initialize the loader with the locales
from fluent.runtime import FluentLocalization, FluentResourceLoader
loader = FluentResourceLoader("l10n/{locale}")

# we would pull all localisations in here and have one huge object in memory
l10n = FluentLocalization(["de", "en-US"], ["main.ftl"], loader) 

# then we can query our localisations like this
val = l10n.format_value("my-first-string")
"Fluent can be easy"

Advantages

contributions to localisation made easy
extra effort, due to versioning in another repository
has implementations for different programming languages

Disadvantages

file system storage
probably versioning in another repository needed
another dependency

WorldsEdgeLink API

Age of Empires API Usage Guidelines

Please check the following Age of Empires API Usage Guidelines before you design or implement anything.

API Root

https://aoe-api.worldsedgelink.com/

Endpoints

Community API - Public, unauthenticated endpoints
Game API - Authenticated endpoints requiring Steam login

Recorded games

https://aoe.ms/replay/?gameId=<game_id>&profileId=<profile_id>

Example request

parameter	type	value	comments
gameId	int64	156900198
profileId	int64	2858362

Where <profile_id> is the perspective of the recorded game. Basically from which client it was uploaded. Matters for view lock.

Authentication

Check our Authentication Helper

General Notes

Some stuff is zlib-compressed. E.g. inside slotinfo there’s a metaData field that seems to be a two-pass base64 string holding binary data.

Example

Heres an example from the slotinfo property:

$ echo 'eNrVkF1PwjAUhv0tvR6GMjYniTeDVWfcgLJ2gvGibl0o3QduEyHG/y6dgUiMF8YLs6uevufknCcP7GkPb2BdFolIuZsnxbmIwcCyTN0yLzVQ1awWRe6OwABqoOYsU2VXAwmLDo39r2QRP5a5vOMbnh5/HqujZbBbNxMdtUZkfMJLVLKMe7NmTlSYs3jXXFE3X6omznjNRqxmYABceWtjguwpQf1pGKvXCe6XNmkybM+6TW+MHQkDiUtPGuYsoGMiocqHFMkdzekidNav8xUaRjCdP11vV6y3haGMQ9/x8/2cjREyAoixT4znuZ5OKKJI5VO6uKHZUhBC1T7bE+4VeNe+u+vAE22dL97giTfVOYj7rP9krvuTud9S9lpBqbeCst8KSqMVlGYrKC/+ifLx7APyMc1P' | base64 -d | zlib-flate -uncompress

12,[{"profileInfo.id":8863869,"stationID":1,"teamID":0,"factionID":0,"raceID":0,"rankLevel":0,"rankMatchTypeID":-1,"timePerFrameMS":0,"isReady":1,"status":0,"metaData":"IkJBRUFBQUF4QWdBQUFETXhBUUFBQURBS0FBQUFOREk1TkRrMk56STVOUk1BQUFCVFkyVnVZWEpwYjFCc1lYbGxja2x1WkdWNENnQUFBRFF5T1RRNU5qY3lPVFVFQUFBQVZHVmhiUUVBQUFBMiI="},{"profileInfo.id":-1,"stationID":-1,"teamID":1,"factionID":-1,"raceID":-1,"rankLevel":0,"rankMatchTypeID":-1,"timePerFrameMS":0,"isReady":0,"status":0,"metaData":""},{"profileInfo.id":-1,"stationID":-1,"teamID":2,"factionID":-1,"raceID":-1,"rankLevel":0,"rankMatchTypeID":-1,"timePerFrameMS":0,"isReady":0,"status":0,"metaData":""},{"profileInfo.id":-1,"stationID":-1,"teamID":3,"factionID":-1,"raceID":-1,"rankLevel":0,"rankMatchTypeID":-1,"timePerFrameMS":0,"isReady":0,"status":0,"metaData":""},{"profileInfo.id":-1,"stationID":-1,"teamID":4,"factionID":-1,"raceID":-1,"rankLevel":0,"rankMatchTypeID":-1,"timePerFrameMS":0,"isReady":0,"status":0,"metaData":""},{"profileInfo.id":-1,"stationID":-1,"teamID":5,"factionID":-1,"raceID":-1,"rankLevel":0,"rankMatchTypeID":-1,"timePerFrameMS":0,"isReady":0,"status":0,"metaData":""},{"profileInfo.id":-1,"stationID":-1,"teamID":6,"factionID":-1,"raceID":-1,"rankLevel":0,"rankMatchTypeID":-1,"timePerFrameMS":0,"isReady":0,"status":0,"metaData":""},{"profileInfo.id":-1,"stationID":-1,"teamID":7,"factionID":-1,"raceID":-1,"rankLevel":0,"rankMatchTypeID":-1,"timePerFrameMS":0,"isReady":0,"status":0,"metaData":""}]

There are also options that use b64(zlib(b64(data))).

Usage Guidelines

Age of Empires API Usage Guidelines

Rate Limits and Access Patterns

The game API has rate limits of approximately 200 requests per minute
Rate limit violations trigger a 429 HTTP error
Recommended configuration: Implement a throttler at 100 requests per 30 seconds for safety

Recommended Access Patterns

Safe to access:

Ongoing games
Match histories
Leaderboards

Optimization Strategy

Use a dual-API approach:

Game API
- Primary use: Fetching ongoing observable games
- Expected usage: 10-15 requests per minute
Community API
- Use for match histories and leaderboards
- Benefits from higher rate limits
- Reduces load on main game API

Actions to Avoid

Accessing chat channels
Accessing presence-related features
Making POST requests
Creating lobbies via API
Any other write operations

Error Handling

Implement logging for rate limit errors (HTTP 429) to monitor API usage patterns

Community API

The Community API provides public, unauthenticated access to Age of Empires game data.

Base URL: https://aoe-api.worldsedgelink.com/community/

Rate Limits

The rate limit for requests to the Community API is 50 requests per second.

OpenAPI Specification

The OpenAPI spec for the /community endpoints can be found at librematch-rlink_client.

Endpoints

Lobby and game listings.

findAdvertisements - Find available game lobbies

Achievement

Player achievements.

getAvailableAchievements - List available achievements
getAchievements - Get player achievements

Clan

Clan information.

find - Search for clans
getClanInfoFull - Get detailed clan information

Community Event

Community events and challenges.

getAvailableCommunityEvents - List available events

External

External service integrations.

proxysteamuserrequest - Steam user data proxy

Item

In-game items and inventory.

getItems - Get available items

Leaderboard

Player rankings and statistics.

getLeaderBoard2 - Get leaderboard data
getRecentMatchHistory - Get recent match history
getStatGroupsByProfileIDs - Get stats by profile IDs

News

Game news and announcements.

getNews - Get game news

Achievement Endpoints (Community)

Public endpoints for querying player achievements without authentication.

Note: These are unauthenticated public endpoints. For authenticated achievement operations, see /game/achievement.

Endpoints

Endpoint	Method	Description
getAchievements	GET	Get unlocked achievements for a player
getAvailableAchievements	GET	Get all available achievements

parameter	type	value	comments
title	str/enum	age1, age2, age3, age4
profileids	arr[int]	[196240]

parameter	type	value
title	str/enum	age1, age2, age3, age4
joinPolicies	arr[int]	[0,1,2]
name	str	“GL
tags	arr[str]	[]
start	int	0
count	int	100

parameter	type	value	comments
title	str/enum	age1, age2, age3, age4
name	str	gli

parameter	type	value	comments
title	str/enum	age1, age2, age3, age4
profileids	arr[int]	[196240]

Keyboard shortcuts

LibreMatch Documentation