<cat>Dev.Backend</cat> <warning>This API is prone to changes at any time - and therefore this guide might go out of date. If something doesn't line up, it probably means the API was changed and that this page needs updating.</warning> This page is an analysis of the API used for the [dev site](https://sbox.facepunch.com/dev/) and the in-game menus; please be aware that this may change at any time and that none of this information is official. All endpoints are on the `https://apix.facepunch.com/` domain. ⤶ # Types⤶ ⤶ NOTE: Nullable types are suffixed with `?`. This API is subject to change and probably⤶ will do so before release.⤶ ⤶ ## PackageType⤶ ⤶ An enum specifying the different package types.⤶ ⤶ Starting at 1:⤶ ⤶ |Index |Name |⤶ |------|----------|⤶ | 1 | Map |⤶ | 2 | Gamemode |⤶ ⤶ ## DownloadInfo (legacy)⤶ ⤶ An object containing a package's download type (where it's hosted, i.e. `github`), and the URL to access it. The `crc` and `size` properties are only available for `upload` types.⤶ ⤶ |Name |Type |Description |⤶ |---------------|----------------|----------------------------------------------|⤶ | type | `string` | The download type of the package |⤶ | url | `string` | Download URL of the package |⤶ | crc | `uint?` | Cyclic redundancy check code |⤶ | size | `int?` | Size of the download in bytes |⤶ ⤶ ## Asset⤶ ⤶ This is returned by `/sbox/asset/get`.⤶ ⤶ |Name |Type |Description |⤶ |---------------|-----------|----------------------------------------------|⤶ | asset | `Package` | This asset's package info |⤶ ⤶ ## Package⤶ ⤶ These are used in various places and are used to describe assets like gamemodes and maps.⤶ ⤶ |Name |Type |Description |⤶ |---------------|-------------------|-------------------------------------------------------|⤶ | Org | `Org` | The organisation owning this package |⤶ | Ident | `string` | This package's identifier |⤶ | Title | `string` | This package's human-friendly name |⤶ | Summary | `string?` | A short description for this package |⤶ | Thumb | `string?` | A URL to this package's thumbnail |⤶ | PackageType | `PackageType` | The package's type |⤶ | Updated | `long` | UNIX timestamp for when the package was last updated |⤶ | Description | `string?` | A longer description for this package |⤶ | ConfigJson | `string?` | A serialized json string containing info for lobbies |⤶ | Background | `string?` | A URL to this package's in-game background |⤶ | Download | `DownloadInfo` | Download information for this package |⤶ | Config | `Config?` | Map & player count config for this package |⤶ | UsersNow | `int` | Number of users currently playing |⤶ | UsersDay | `int` | Number of users that played today |⤶ | UsersMonth | `int` | Number of users that played this month |⤶ | UsersTotal | `int` | Number of users that have ever played |⤶ | Tags | `string[]` | A list of tags that describe this package. |⤶ | CategoryId | `int` | The category's identifier of this package. |⤶ | SubCategoryId | `int` | The subcategory's identifier of this package. |⤶ | Version | `Version?` | The version of this package. |⤶ | Favourited | `int` | Number of people that favorited this package. |⤶ | VotesUp | `int` | Number of votes up for this package. |⤶ | VotesDown | `int` | Number of votes down for this package. |⤶ | Source | `string` | A link to the source of this package. |⤶ | Public | `bool` | Whether this package is public. |⤶ ⤶ ## Version⤶ ⤶ An object containing info about how the game should fetch assets through the new download system.⤶ ⤶ |Name |Type |Description |⤶ |----------------------|----------|--------------------------------------------------------------|⤶ | FileCount | `int` | Number of files |⤶ | TotalSize | `int` | Total game size in bytes |⤶ | AssetVersionId | `int` | This version's ID |⤶ | Created | `string` | The timestamp for when this version was created |⤶ | Manifest | `string` | A serialized json string containing a list this game's files |⤶ ⤶ ## MenuPackage⤶ ⤶ These are used in the menu (search, "trending", etc) to show a package without loading all of its data.⤶ ⤶ |Name |Type |Description |⤶ |---------------|-------------------|-------------------------------------------------------|⤶ | org | `Org` | The organisation owning this package |⤶ | ident | `string` | This package's identifier |⤶ | title | `string` | This package's human-friendly name |⤶ | summary | `string?` | A short description for this package |⤶ | thumb | `string?` | A URL to this package's thumbnail |⤶ | packageType | `PackageType` | The package's type |⤶ | updated | `long` | UNIX timestamp for when the package was last updated |⤶ | usersNow | `int` | Number of users currently playing |⤶ | usersMonth | `int` | Number of users that played this month |⤶ | usersTotal | `int` | Number of users that have ever played |⤶ | tags | `string[]` | A list of tags that describe this gamemode. |⤶ ⤶ ## Org⤶ ⤶ These are used in various places and are used to describe organisations.⤶ ⤶ |Name |Type |Description |⤶ |---------------|----------|----------------------------------------------|⤶ | ident | `string` | This organisation's identifier |⤶ | title | `string` | This organisation's human-friendly name |⤶ | description | `string?`| This organisation's description |⤶ | thumb | `string?`| A URL to the organisation's chosen thumbnail |⤶ | socialTwitter | `string?`| A URL to the organisation's Twitter account |⤶ | socialWeb | `string?`| A URL to the organisation's website |⤶ ⤶ ## Config⤶ ⤶ These are used to provide the game with info about how a gamemode should be set up.⤶ ⤶ |Name |Type |Description |⤶ |----------------------|----------|----------------------------------------------|⤶ | showMapSelect | `bool` | Show the map select screen? |⤶ | defaultMap | `string` | Default map |⤶ | minPlayers | `int` | Minimum number of maxplayers |⤶ | maxPlayers | `int` | Maximum number of maxplayers |⤶ | clientDownloadShared | `bool` | Client downloads gamemode? |⤶ This page is an analysis of the API used for the [dev site](https://sbox.facepunch.com/dev/) and the in-game menus; please be aware that this may change at any time and that none of this information is official. All endpoints are on the `https://sap.facepunch.com/` domain. # Endpoints ## GET /sandbox-asset⤶ ## GET /asset/{ident}⤶ ### Params ⤶ `id`: An identifier (`org`.`package`) for the asset you wish to retrieve info about. ⤶ `ident`: An identifier (`org`.`package`) for the asset you wish to retrieve info about. ### Returns An `Asset` ### Example Request ⤶ [/sandbox-asset?id=facepunch.pool](https://apix.facepunch.com/sandbox-asset?id=facepunch.pool) ⤶ [/asset/facepunch.construct](https://sap.facepunch.com/asset/facepunch.construct) ### Example Response ``` { "Asset": { "Org": { "Ident": "facepunch", "Title": "Facepunch", "Description": "", "Thumb": "https://files.facepunch.com/sbox/org/facepunch/logo.1.png", "SocialTwitter": "", "SocialWeb": "" }, "Ident": "pool", "Title": "Pool", "Summary": "A classic pub game where your skill is determined by your blood-alcohol content.\r\n", "Description": "A classic pub game where your skill is determined by your blood-alcohol content.\r\n", "Thumb": "https://files.facepunch.com/sbox/org/facepunch/pool/thumb.b52e5af8.jpg", "Background": "https://files.facepunch.com/sbox/org/facepunch/pool/background.21884981.jpg", "PackageType": 2, "Updated": 1619706156, "Download": { "Type": "github", "Url": "https://github.com/Facepunch/sbox-pool/tree/master" }, "ConfigJson": "{\"MinPlayers\":1,\"MaxPlayers\":2,\"NetworkType\":0,\"MapList\":[\"pool_lounge_v2\"],\"MapSelection\":1,\"RankType\":1,\"LeaderboardType\":1}", "UsersNow": 0, "UsersDay": 4, "UsersMonth": 55, "UsersTotal": 2191, "Tags": [ "!mousekeyboard", "multiplayer", "mousekeyboard" ], "CategoryId": 3, "SubCategoryId": 0, "Version": null, "Favourited": 65, "VotesUp": 87, "VotesDown": 2, "Source": "https://github.com/Facepunch/sbox-pool/tree/master" } } ``` --- ## GET /sandbox-asset-list⤶ ## GET /asset/list⤶ ### Params `type`: `map` or `gamemode`. `order`: `trending`, `popular`, `newest`, `live`. Defaults to `trending`. `search`: Any search query. `category` (An Index Value starting at 1): | Index | Category | |:-------:|:---------------------:| |1 | SandBox | |2 | Tech Demo/Expermental | |3 | Sports | |4 | Shooting | |5 | Parkour | |6 | Social | |7 | Meme | |8 | Roleplay | |9 | Racing | |10 | Mystery | |11 | Survival | |12 | Animals | |13 | Food | |14 | Strategy | |15 | Space | |16 | Fighting | |17 | Retro | |18 | Music | |19 | Art | |20 | Tycoon | |21 | Streamer | ### Returns A list of `Package`s. ### Example Request [/sandbox-asset-list?type=map&order=trending&search=Construct](http://apix.facepunch.com/sandbox-asset-list?type=map&order=trending&search=Construct) ### Example Response ``` [ { "Org": { "Ident": "facepunch", "Title": "Facepunch", "Thumb": "https://files.facepunch.com/sbox/org/facepunch/logo.1.png" }, "Ident": "construct", "Title": "Construct", "Summary": "A simple construct map", "Description": "This is the default map. It both has purpose and no purpose.", "Thumb": "https://files.facepunch.com/sbox/org/facepunch/construct/thumb.2f5f6e0a.jpg", "PackageType": 1, "Updated": 1643893793, "UsersNow": 0, "UsersDay": 134, "UsersMonth": 1580, "UsersTotal": 7774, "Tags": [], "CategoryId": 0, "SubCategoryId": 0, "Favourited": 0, "VotesUp": 0, "VotesDown": 0, "Source": null }, { "Org": { "Ident": "cstruct", "Title": "egg corporation's things", "Thumb": "" }, "Ident": "gm_construct", "Title": "gm construct", "Summary": "Bad port, but is working port!", "Description": "A bad port of gm_construct v13, that I am trying to get fixed-ish. I fully expect someone else to come along and do it better than I can, and if you have a problem with this version I encourage you to make your own. I'll give you all the files if you ask.\r\n\r\nVERSION HISTORY:\r\nV1 Release\r\nV1.1 Fixed some weird white sprites and also added some basic baked lighting(dark room now dark again)\r\nV1.1.1 Ladder for secret room works now. It's literally a stack of clipbrushes, basically very narrow invisible stairs, but that might unironically be better than Source 1 ladders, lmao\r\nV1.2 Added Long Description into map, this is now a \"cool release\" until I get the urge to work on it more. Contact me if it breaks, if you can.", "Thumb": "https://files.facepunch.com/sbox/org/cstruct/gm_construct/thumb.3464c8e.jpg", "PackageType": 1, "Updated": 1630804910, "UsersNow": 0, "UsersDay": 3, "UsersMonth": 102, "UsersTotal": 1458, "Tags": [], "CategoryId": 0, "SubCategoryId": 0, "Favourited": 0, "VotesUp": 0, "VotesDown": 0, "Source": null } ] ``` ⤶ # Other⤶ ⤶ ## Finding an Org⤶ ⤶ There's no known endpoint for organizations. This is the closest you can get:⤶ ⤶ 1. Visit several endpoints (`/asset/find?type={map}|{gamemode}`, `/menu/index`) and collect a list of orgs with their gamemode idents⤶ 2. Search that list for an org that matches the ident we're looking for⤶ 3. Visit `/asset/get?id={org}.{ident}`⤶ 4. Get the title & description for the org from this⤶ ⤶ ## Player Counts⤶ ⤶ Player accounts appear to use the Steam Lobby API; this means that an active Steam instance is required, using an account with access to s&box.⤶ ⤶ To enumerate through lobbies, use [Steamworks.SteamMatchmaking.LobbyList](https://wiki.facepunch.com/steamworks/SteamMatchmaking.LobbyList).⤶ ⤶