Project Files Overview - theRAPTLab/gsgo GitHub Wiki

Project data is read and saved as separate project files. When a project is loaded, it is read from a *.gemprj file and loaded into the database. Any changes to the project (e.g. editing project metadata, rounds, blueprints, and instances) are all automatically written to both the database and project file.

(There is a one second delay in writing to queue keystrokes and reduce the frequency of writing).

Project files are all saved in an arbitrary 'root' folder under gsgo/gs_assets. Only one 'root' folder is opened by the GEMSTEP app. By default, the root is local.

IMPORTANT: DO NOT COMMIT your gs_assets folder!!! Each simulation server shoudl have its own unique gs_assets folder.

Inside the root folder should be two folders:

• projects
• sprites

e.g. by default most servers should have the following folders:

gsgo/gs_assets/local/projects
gsgo/gs_assets/local/sprites

The 'root' folder can be named anything and placed anywhere under gsgo/gs_assets. You can take advantage of this to arrange folders however is most convenient for you. Use this to manage sets of projects for different locations/dates/sites/groups/studies/etc.

For example, if you have a single server machine that will be used in 'room13' and 'room21', but when you're in one room, you only want to see projects from that room, you can arrange projects like this:

gsgo/gs_assets/room13
gsgo/gs_assets/room21

On the other hand, if you wanted to nest folders, you could also do something like this:

gsgo/gs_assets/orgs/iu/fall2021/morning
gsgo/gs_assets/orgs/iu/fall2021/afternoon
gsgo/gs_assets/orgs/iu/fall2021/serverB
gsgo/gs_assets/orgs/iu/winter2021/all
gsgo/gs_assets/orgs/vu/sept2021/day1
gsgo/gs_assets/orgs/vu/sept2021/day1

Each of these folders would be a project root and contain any number of project files and sprites.

You can use gs_packages/gem-srv/config/local-settings.json to override the default local project root.

To set the project root, add a GS_ASSETS_PROJECT_ROOT variable to local-settings.json, e.g.

• To use gsgo/gs_assets/room13:

  const GS_ASSETS_PROJECT_ROOT = 'room13';

• To use gsgo/gs_assets/orgs/iu/fall2021/morning:

  const GS_ASSETS_PROJECT_ROOT = 'orgs/iu/fall2021/morning';

NOTE: No trailing / is needed.

For convenience you can always just leave the local folder setting and just stuff all of your projects there.

(gsgo-settings.js defines the default project root local. You should not change this.)

Inside the 'root' folder, you always need to define a projects folder and a sprites folder. The projects folder contains all the individual project files. The sprites folder contains sprites shared across all the projects.

Project filenames need to be unique. So if you have multiple groups working on similar files, you would name them according to the group. For example:

gsgo/gs_assets/room13/projects/aquatic_grp1.gemprj
gsgo/gs_assets/room13/projects/aquatic_grp2.gemprj
gsgo/gs_assets/room13/projects/aquatic_blue.gemprj
gsgo/gs_assets/room13/projects/aquatic_green.gemprj

Project filenames are now used as the URL parameter for the project. For example, gsgo/gs_assets/room13/projects/aquatic_grp1.gemprj can be opened via:

http://localhost/app/project?project=aquatic_grp1

The sprites folder should contain all the spritesheet definitions (json) and graphics (png) files shared by all projects.

gsgo/gs_assets/room13/sprites/algae.json
gsgo/gs_assets/room13/sprites/algae.png
gsgo/gs_assets/room13/sprites/bee.json
gsgo/gs_assets/room13/sprites/bee.png

(There is no longer a need to add and maintain a assets.json file. Asset lists are now generated automatically.)

New projects can be created by creating a new project from a project template file. Use this to define a base project for students to work on. They would then create a new project based on the template and modify that new project.

Any project file can be converted into a template file by adding a _template_ prefix to the name.

So a typical curriculum development workflow might be something like this:

1. Work on aquatic.gemprj until you feel like it's at a good starting point for students.
2. Rename aquatic.gemprj to _template_aquatic.gemprj
3. When a student logs onto the system and wants to create a new project, they will see the template aquatic file.
4. When they select the template, they will be prompted to enter a new filename.

Projects are ALWAYS read from the *.gemprj files. So you can easily just add more *.gemprj files to the project root, or replace any existing ones. Even if a project file was previously opened and stored in the database, when you open it again, it will be read fresh from the *.gemprj file and saved to the database.

The *.gemprj format is basically a modified JSON format.

• You can edit the *.gemprj with a text editor if needed.
• You should be able to set your text editor to treat it as a JSON or javascript file to get syntax highlighting.
• To make the files more editable we convert script lines into template literals with carriage returns. This technically makes the project file invalid JSON.
• All other text should be double-quoted, including key names.

Changing the id of a project in the Project Settings editor UI will cause the app to save the project with a new name matching the new id. The old project file will remain. This is effectively a duplicate/save-as feature.

See also !159