Package structure

A Green Games game is a package of data and scripts. It is not a web page: it carries no HTML, no CSS and no code that touches the browser or your computer. The game declares its world in JSON files and its logic in a script that only knows the Green Games API. The program that shows it (the portal, the launcher or the editor) is the only one that draws, reads the keyboard and saves data.

This section is for people who write those files by hand. If you would rather build the game without code, the editor writes the same files for you: Tour of the editor.

The format is written in Spanish: file names, JSON keys, API names and the output of the command-line tool. The examples in this section come from real files and are quoted as they are, with their comments in Spanish.

What you need#

Availability#

The contract (format 1, API 1) has grown since its first version, always by adding things. Today everything you use or download ships the same engine:

This section of the documentation describes that full contract, which today is version 1.2: actors, camera, labels, views (third person, first person, side-on 2D, from above, isometric), sprites, tile maps, multiplayer on the same computer and, with version 1.1, the cube terrain of the open world, the pointer and the hotbar, and with version 1.2, models, textures and recorded sounds. A .ggx that validates runs the same in all four.

What no published app offers yet is online multiplayer: the format already lets you declare it (multijugador.enLinea), but there are no rooms over the internet. See Roadmap.

The folders of a game#

Each game lives in its own directory. The name of the directory is the game's id.

mi-juego/
  juego.json               manifest: name, difficulties, controls, score tables, texts
  escenas/principal.json   one or more scenes: pieces, spawn points, zones, lights, view and tile maps
  laminas/moneda.json      optional: sprites, pixel drawings written as text
  scripts/principal.ts     the logic, in TypeScript or JavaScript, with the Green Games API
  recursos/portada.svg     packaged resources (today: the cover image)
  modelos/robot.glb        optional: 3D models (version 1.2)
  texturas/ladrillo.png    optional: images for the material of pieces (version 1.2)
  sonidos/campana.wav      optional: recorded sounds (version 1.2)
  creditos.json            author and license of each model, texture and sound (version 1.2)
  pruebas/bot.json         script for the bot that plays the match from start to finish

greengames empaquetar (or Export game in the editor) turns that folder into one .ggx file. The same .ggx runs in the portal, in the launcher and in the editor. What it holds: The .ggx format.

Units and axes#

• Y is up. The avatar faces +Z when its rotacionY is 0.
• One unit is roughly half an avatar wide. The avatar is 0.8 wide and 1.8 tall.
• Rotations are in degrees, in Y-X-Z order (it turns around Y first).
• The simulation advances at a fixed 60 frames per second: the time step dt is always 1/60. Why: Determinism.

Measurements for level design#

With these numbers you decide the width of a gap or the height of a step before you test. They are the default values; the script can change each player's speed and jump, and the scene can change its gravity.

A player who falls below alturaCaida goes back to their spawn point.

The life cycle of a match#

1. The game player loads the .ggx, validates it and shows the start screen (cover, difficulty, controls). That screen, the pause menu and the end panel are provided by the game player: the game does not program them.
2. When you press Play it creates the isolated room and hands it the package, the options (difficulty, language, seed, mode) and the saved data (progress and scores).
3. The room loads the initial scene, with only the pieces of the chosen difficulty, and creates the players at the first spawn point.
4. The script runs once (the top-level code), and then whatever was registered with juego.alIniciar.
5. Every frame, in this order: piece movements, players (input, jump, gravity), actors, physics, player touches and zones, actor touches, collisions between pieces, actions, timers, stopwatches and, last, juego.cadaCuadro.
6. juego.terminar(...) stops the room. The game player shows the end panel.

Three things follow from that order:

• The changes the script makes in one frame are seen in the next.
• If a script event throws an error, the match goes on, the error is reported and greengames probar fails.
• A press shorter than one frame is not lost: it still reaches the jump and jugadores.alAccion.

The whole path#

1. Create the game. greengames crear mi-juego --nombre "Mi juego" leaves a folder with a small, complete game (collect coins against the clock) that already passes validation and the test. With --tipo you pick another starting template (first person, 2D platformer, top-down view, isometric, hybrid or multiplayer): crear.
2. Decide the game in one sentence. What the player does, how they win, how they lose and which number measures how well they did. Example: "Cross the circuit to the goal; you win by arriving, you lose if time runs out; the score is the time".
3. Build the scene in escenas/principal.json: first the floor and the spawn points, then the rest. See Scenes.
4. Write the script in scripts/principal.ts. See Scripts and the API reference.
5. Write the bot script in pruebas/bot.json: the bot must be able to win on every difficulty. See Testing with the bot.
6. Validate. greengames validar mi-juego checks files, schemas, script types and rules. Fix every error and read every warning. What each code means: The validator.
7. Test. greengames probar mi-juego plays the match with no screen, on each difficulty and with two seeds. To see it with your own eyes: greengames previsualizar mi-juego.
8. Package. greengames empaquetar mi-juego writes the .ggx. A game with errors is not packaged.

Every command, with its options and its real output: The greengames tool.

Next#

• The manifest: the game's card, property by property.
• Case study: a real game, read from start to finish.
• Limits: how much fits in a package and in a match.