ConstructServices 1.3.0

Construct-Services-DotNet-Class-Library

The official Construct Services .NET library, supporting .NET Standard 2.0+.

Installation

Using the .NET Core command-line interface (CLI) tools:

dotnet add package ConstructServices

Using the NuGet Command Line Interface (CLI):

nuget install ConstructServices

Using the Package Manager Console:

Install-Package ConstructServices

From within Visual Studio:

1. Open the Solution Explorer.
2. Right-click on a project within your solution.
3. Click on Manage NuGet Packages...
4. Click on the Browse tab and search for "Stripe.net".
5. Click on the Stripe.net package, select the appropriate version in the right-tab and click Install.

Documentation

You can read the full API documentation here. Below are links to documentation and examples for using this package.

Usage

Before you start

You need to create a Construct Game Services account. From here, you can create a new Game, and get your Game ID, which is required to make requests to these services.

Translated content

When text content is returned from a service, it is returned in the original language it was written in. The object is returned with properties such as:

{
	title: "My Test Title",
	text: "Example test string",
	originalLanguage { 
		iso: "EN", 
		englishName: "English"
	}
	responseLanguage { 
		iso: "EN", 
		englishName: "English"
	}
}

By setting a requested language before making the request, the text will be returned in the requested language if your plan supports the translation. For example, setting:

// Returns all translatable text content in response objects to German
service.SetRequestedLanguage(TargetLanguage.German);

Could return the above example object as:

{
	title: "Mein Testtitel",
	text: "Beispieltestzeichenkette",
	originalLanguage { 
		iso: "EN", 
		englishName: "English"
	}
	responseLanguage { 
		iso: "DE", 
		englishName: "German"
	}
}

If the translation cannot be served (typically because your plan doesn't support it) the request will fail gracefully, and simply return the original untranslated string:

{
	title: "My Test Title",
	text: "Example test string",
	originalLanguage: { 
		iso: "EN", 
		englishName: "English"
	}
	responseLanguage { 
		iso: "EN", 
		englishName:"English"
	}
}

Culture formatting

When an object is returned from a service, a lot of the times it will contain properties such as:

{
	count: 1000,
	formattedCount = "1,000",
	date = "06/03/2026 15:18:42",
	formattedDate = "06/03/2026 15:18:42",
}

By setting the service culture before making the request, the formatted versions of the properties will be returned in the specified culture. For example, setting:

// Returns all dates, numbers formatted to German culture
service.SetCulture(new CultureInfo("de-DE"));

Would return the above example object as:

{
	count: 1000,
	formattedCount = "1.000",
	date = "06/03/2026 15:18:42",
	formattedDate = "06.03.2026 15:18:42"
}

Pagination

Some requests return results in paginated form. For these requests, you'll need to pass in a new PaginationOptions object:

var requestedPage = 1;
var recordsPerPage = 20;

var result = service.ListPlayers(new ListPlayersOptions {
        Ordering = PlayerOrdering.Newest
    },
    new PaginationOptions(requestedPage, recordsPerPage)
);

This then returns:

var hasMore = result.Pagination.HasMore;
var totalPages = result.Pagination.TotalPages;
var totalRecords = result.Pagination.TotalRecords;

Using these properties you can make further requests to fetch results on other pages.

Update Requests

A request to update something might look like this:

service.UpdateObject(
    objectID,
    new UpdateOptions
    {
        Title = "New Title",
        Description = "New description"
    }
);

When making these requests, you only need to specify the properties you wish to change. Any unspecified properties in the update options will not be updated.

Object Ratings

When you fetch a ratable object, a rating status object will be returned with the object. The property IsRatable indicates if this particular object can be rated or not (you can disable ratings on objects in your CGS account.)

If the object is ratable, a rating aggregate object will be available which gives you a summary and some other information about the ratings for this object.

var service = new CloudSaveService(gameID);
var getResult = service.GetCloudSave(cloudSaveID);
if (getResult.Success)
{
    var cloudSave = getResult.CloudSave;
    var ratingStatus = cloudSave.RatingStatus;

    if (ratingStatus.IsRatable)
    {
		// The dimensionless rating
        var dimensionlessRating = ratingStatus.Ratings[string.Empty];
        var averageRating = dimensionlessRating.AverageRating;
        var totalRatings = dimensionlessRating.TotalRatings;

		// A dimension rating (if this object has additional rating dimensions)
        var dimensionRating = ratingStatus.Ratings["dimensionid"];
        var averageDimensionRating = dimensionRating.AverageRating;
    }
}

An additional property ratingStatus.MyRatings is returned if the request is authenticated with a players session key. This contains details on the rating values this player has cast on this object.

The Services

• Authentication Service

  Allow players to sign in to your game/application with username & password, Apple, BattleNet, Discord, Email magic links, Facebook, Github, Google, ItchIO, Microsoft, Patreon, Reddit, Steam, X and Yandex.

  Once a player is signed in, they can also:

  • Change their player name (displayed to other users)
  • Set an avatar
  • Link their account to other login providers allowing for multiple sign in optionsh
  • Delete their account
  • Set an email address for their account
  • Request a forgotten password

  See the Examples or read the full API documentation

• Broadcast Service

  Allows you to create Broadcast Channels, and from these channels create Broadcast Messages that are accessible to all players in your game/application. For example, you might create a channel "New Features" and publish messages into this channel describing new features you have introduced when you update your game.

  Messages can be translated into multiple languages to cater to international audiences. If enabled, players can also rate Broadcast Messages.

  See the Examples or read the full API documentation

• CloudSave Service

  Allow players to save blobs of data into the cloud for retrieval at a later date. The most useful and simple applciation for this is allowing players to save their game progress. You can also save a picture alongside a cloud save to represent the data more visually - for example a screenshot of the game where the save game was created.

  You can also create public Game Buckets that players can save data into - for example if your game allows you to create custom levels, you could create a public bucket for these levels and allow players to share their creations with other players. These data blobs can also be rated with multiple dimensions, and returned to players sorted by the ratings.

  See the Examples or read the full API documentation

• Leaderboard Service

  Unlike other services, CGS leaderboards automatically track scores by country allowing you to see how players from different countries are performing for specific leaderboards.

  CGS leaderboards boast a large array of advanced features built in:

  • Format scores for all types of values, time, money, points etc.
  • Group players into Tiers/Divisions
  • Assign players to teams and customise how teams are ranked
  • Show daily, weekly, monthly or annual leaderboards
  • Track players historic performance showing how their rank is improving over time
  • Shadow ban players to prevent cheaters from spoiling the experience of legitimate players
  • Set up thresholds that automatically reject scores if they fall outside of expected ranges
  • Store additional values with scores to provide extra context when viewing leaderboards (for example, how many gold coins were collected)

  See the Examples or read the full API documentation

• XP Service

  Tracks player XP. The XP service allows you to:

  • Add, remove or set a players XP
  • Define ranks for XP, unlocked by players when they reach certain XP levels.
  • Define periods where XP earnt is multiplied by a custom amount (EG a 3x XP bonus weekend)

  See the Examples or read the full API documentation

Support

For any requests, bug or comments, please open an issue or submit a pull request.