Skip to content

An unofficial supplement to Daybreak Game Company's Census API, which uses alternative data sources to present up-to-date and expanded PlanetSide 2 data.

License

Notifications You must be signed in to change notification settings

PS2Sanctuary/Sanctuary.Census

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Sanctuary.Census

An unofficial supplement to Daybreak Game Company's Census API, which aims to present up-to-date and more in-depth PlanetSide 2 data. Data retrieval is fully automated, although major PlanetSide 2 updates will often require small changes in order to update certain collections, which can take a small amount of time to implement.

Sanctuary.Census is in no way affiliated with nor endorsed by either Daybreak Games Company or Rogue Planet Games.

Want to chat with developers of all things Census related? Come say hello in the Planetside Community Developers Discord!
Discord

Getting Started

An instance of Sanctuary.Census can be found at https://census.lithafalcon.cc/. It largely provides the same query interface as the official Census, so ensure you are familiar with using that. I'd recommend reading Leonhard's Census Primer if you're not.

Jump right in by heading to https://census.lithafalcon.cc/get/ps2 to view the available collections. Auto-generated API documentation can be found here.

Sanctuary.Census has a (somewhat primitive) 'realtime' event-stream. Events are pushed every five seconds when operating nominally, but are likely to come in bursts with up to a minute of downtime, and occasionally may fail completely for a particular server for multiple hours.

  • Connect at wss://census.lithafalcon.cc/streaming.
  • Compatible with the official Census' event stream.
  • Valid event names: WorldPopulationUpdate, MapStateUpdate.

Warning: Please read the migrating from Census documentation to get an overview of any differences between Sanctuary.Census and the official Census.

Namespaces

Sanctuary.Census only provides two namespaces:

  • ps2 - data from the current 'live' release of the game.
  • pts - data from the current 'test' release of the game.

The describe verb

Sanctuary.Census provides some collections, and fields on existing collections, that the official Census does not have. In order to better understand these collections, the describe verb may be used to obtain typing information and descriptions of the collection's fields.

GET /describe/<namespace>/<collection>
e.g https://census.lithafalcon.cc/describe/ps2/fire_mode_2

Building and Deployment

To build and run Sanctuary.Census, you'll require the .NET 7 SDK. Furthermore, you'll need access to a MongoDB instance. This is simple to install locally. Sanctuary.Census expects the database to be running on the default endpoint of localhost:27017, and there is currently no way to configure this.

If you intend to deploy your own copy, each application is ready to send logging to a Seq deployment, and OpenTelemetry tracing/metrics to an OTLP-compatible endpoint (such as Jaeger or the OTEL Collector). Each application that exposes an API expects to be hosted behind a reverse proxy (in particular, configuration has been performed for Nginx).

Warning: A large number of adjustments will be required to compile successfully, as I have not open-sourced the server data retrieval component.

Solution Architecture

Sanctuary.Census is comprised of independent services responsible for the following primary tasks:

  • Data exposure (e.g. the API).
  • Static collection data extraction and collation.
  • Realtime data retrieval.

Sanctuary.Census.Common

This project contains the collection models, along with other shared services and types, such as JSON converters and the base database context.

Sanctuary.Census.Api

This project is responsible for serving Census REST queries, via an ASP.NET Core Web API. This encompasses parsing the Census REST query format, building a corresponding query to the underlying MongoDB database, and converting the result into a JSON model compatible with expected Census results.

Sanctuary.Census.Builder

This service worker project is responsible for transforming data source caches into the collections surfaced by the API. Built collections are upserted in the underlying database, and the builder also maintains a diffing provider, in order to show changes to the collections.

The builder uses multiple data source projects - for example, Sanctuary.Census.ClientData. Data source projects contain their specific data models, data retrieval logic and an object inheriting from IDataCacheService responsible for caching their data.

Sanctuary.Census.RealtimeHub

This project is responsible for processing realtime data, which includes upserting the database collections and distributing updates over the EventStream, which includes responsibility for managing the WebSocket connections. It receives data from the realtime collectors via a gRPC service and uses an ASP.NET Core Web API to provide WebSocket support.

Sanctuary.Census.RealtimeCollector

This project contains an independent game server client that is responsible for connecting to a server and retrieving realtime data. Collected data is sent to the realtime hub using a gRPC connection. Collectors work most efficiently when connecting to only a single server, but have support for synchronously cycling between multiple servers.

Contributing

Contributions are more than welcome! Please consider opening an issue first to detail your ideas. This gives a maintainer a chance to pre-approve the work, and reduces the likelihood of two people working on the same feature simultaneously.

About

An unofficial supplement to Daybreak Game Company's Census API, which uses alternative data sources to present up-to-date and expanded PlanetSide 2 data.

Topics

Resources

License

Stars

Watchers

Forks

Languages