GmCommon
GmCommon is GreenMind's Unreal Engine plugin. An org uses it under a licence GreenMind issues, and downloads its builds from the org's GmCommon page in the console.
Licences are issued by GreenMind, not made in the console. To license GmCommon, press Request a GmCommon licence on the org's GmCommon page: choose the tier and the seats, and say where we should reply. The request reaches GreenMind's support team with your org and its plan attached, and the page shows that it is waiting until we answer. Use it again to add seats or change a licence's expiry; anybody holding Licences on the org (its admins do) can make it.
Tiers
| Tier | Opens |
|---|---|
| Binary | Every build, for each engine version and platform |
| Source | Every build, and the source archive |
An org can hold more than one licence. Downloads follow the highest tier among its licences that are neither revoked nor expired.
Who can see what
Two permissions, held on the org (see Concepts):
| Permission | Allows |
|---|---|
manage_licences |
See the org's licences and the machines holding them, and release one |
download_sdk |
Download the builds the org's licences open |
An org's admins hold both. Anyone else needs a role that grants them.
Licences and seats
The plugin checks its licence only in the editor. The check never ships in your game, so your players never need to reach us. The editor does: the plugin has to reach the platform to check its licence, and it keeps working through short network lapses because the token it holds lasts 7 days (see below). Every licence is checked this way; there are no offline licences.
A licence has a key, gmlic_<licence id>_<secret>, which GreenMind sends you once when the licence is issued. Only a hash of it is kept, so nobody can show it to you again; if it is lost, ask for a new licence. Treat it like a password: anyone holding it can take your seats.
Each machine the plugin runs on activates the licence with the key and takes one seat. A licence has a number of seats, and a machine beyond that number is refused until one is freed.
- Activating again is free. A machine that already holds a seat keeps it; it is known by a hash of an id the plugin reads from the machine, so we never learn your hostnames.
- Seats come back by themselves. A machine that has not checked in for 7 days no longer holds a seat, so a wiped build agent does not keep one for ever. It takes a free seat again the next time it activates.
- Releasing a machine frees its seat at once. Do it from the GmCommon page, or the plugin can release its own machine. The released machine's next check is refused, which ends its token there and then, and it needs a seat again: someone has to activate it on purpose, since the plugin does not do it by itself after a release. A released machine that never reaches the platform again works until its current token runs out.
- Revoking a licence refuses every machine at its next check.
How the plugin checks a licence
The plugin's licensing is built on the licence routes of the platform API, with the licence key as its bearer token. They take no server key and no player token, and act in no environment.
Authorization: Bearer gmlic_<licence id>_<secret>
| Method | Path | Body | Answers |
|---|---|---|---|
POST |
/licence/activate |
{ machineHash, label? } |
An activation |
POST |
/licence/check |
{ machineHash } |
An activation |
POST |
/licence/release |
{ machineHash } |
204, held seat or not |
GET |
/licence/jwks.json |
none, and no credential | The public key, as a JWKS |
machineHash is the SHA-256, 64 lowercase hex characters, of an id the plugin reads from the machine. label is up to 80 characters the console shows beside the machine, such as build-agent-3.
An activation looks like this:
interface LicenceActivationResult {
token: string // an Ed25519-signed JWT
tokenExpiresAt: string // ISO 8601
licence: {
id: string
orgId: string
product: 'gmcommon'
tier: 'binary' | 'source'
seats: number
expiresAt: string | null
}
}
The token lasts 7 days, or until the licence expires if that is sooner. The plugin keeps it and checks its signature against the public key without a request, so the editor still starts during a network lapse, for as long as the token lasts. It renews the token with /licence/check when it starts and at least daily while it runs. A machine that cannot reach the platform for longer than that stops working until it can.
A refusal is { error, message, details? }, as elsewhere in the API:
| Status | error |
When |
|---|---|---|
| 401 | unauthorized |
No licence key, or one that is not valid |
| 403 | forbidden |
The licence is revoked or expired, or a check from a machine whose seat was released; message says which. The plugin drops its token |
| 403 | quota-exceeded |
Every seat is in use; details.limit is how many there are |
| 404 | not-found |
A check from a machine that holds no activation; activate again |
| 400 | invalid-request |
The body is not as described above; details.field names what is wrong |
| 413 | payload-too-large |
The body is over 16 KB |
| 429 | rate-limited |
Too many requests from one address in a minute; wait for Retry-After |
Downloads
The Downloads part of the GmCommon page lists every build the org's licences open, by version, engine version and platform, with its size and SHA-256. Check the SHA-256 of an archive before you use it.
A download link lasts 15 minutes and is made when you press Download, after the org's licence is checked. Every download is recorded against the org and the person who made it.