Gdevelop: Rules and structure to get your assets in the Assets Store

[Entr0py404]

We have started a team for the asset store with trello like the extension team.
https://trello.com/b/xoOCKFOf/gdevelop-assets

We want to know some guidelines and what licensing are going to be acceptable.

[4ian]

Here are the rules for the assets to be imported in the Assets Store

The main idea is that assets are grouped into folders and sub folders. Images, audio and fonts should have a name that is the plain English name that will be displayed to the user. By giving specific names to images, they will be used to create a single object.

Note that tilesheets are not supported! Each image of an object must be in a separate file (using the rules to name the files below). It's also recommended that all images of a single object have the same size (with transparent margins), because for now we can't specify the origin of an image.

For images (to make sprite, tiled sprite or panel sprite objects):

Each image will be used to create an object. For sprites, more than one image can be used to create a single object, by following the rules described below.

• By default, an image will be used to create a Sprite object.

  • The name of the file, without the extension, will be used for the object name.

  For example, an image called "Spaceship.png" will create a Sprite object called "Spaceship", with this image as the first animation.

  • If the object is animated, use different image files with the same base name, and add an underscore followed by the image index: Spaceship_1.png, Spaceship_2.png, Spaceship_3.png.

  • If the object has multiple animations, you can add the name of the animation between the base name and the index.

  For example: Spaceship_flying_1.png, Spaceship_flying_2.png, Spaceship_flying_3.png, Spaceship_1.png, Spaceship_idle.png, Spaceship_damaged_1.png, Spaceship_damaged_2.png will create an object with three animations: Flying (3 images), Idle (1 image), Damaged (2 images)

  • To specify the speed of the animations and if they are looping, create a file with the same base name suffixed by _METADATA.json. For example: Spaceship_METADATA.json. Inside, put this JSON:

  {
      "timeBetweenFrames": 0.2,
      "loop": false
  }
  

  For example:

  • In the future, we'll support one _METADATA.json file for each animation. For now, just one is supported for all animations of the object.

• If you want to create a Tiled sprite (for backgrounds or repeating patterns):

  • Prefix the base name by tiled_. For example: tiled_Grass Background.png

• If your image is a 9 patch, that can be stretched with the center and the border repeated:

  • Slice your image in 9 different images, and name them: 9patch_base name_gravity.png with gravity being: southwest, southeast, south, northwest, northeast, north, west and east.

  For example: 9patch_Orange leaves_center.png, 9patch_Orange leaves_east.png, 9patch_Orange leaves_north.png, 9patch_Orange leaves_northeast.png, 9patch_Orange leaves_northwest.png, 9patch_Orange leaves_south.png, 9patch_Orange leaves_southeast.png, 9patch_Orange leaves_southwest.png, 9patch_Orange leaves_west.png,.

Organizing the assets with tags

Put all your images in a folder. In this folder, create a file called `TAGS.md`. In this file, put the tags of the assets, separated by a comma. Put at least a tag `top-down`, `side view` or `interface`. For example: md5-38a787b324a41ff825c30e75187478f7 You can put your images in different sub folders. Each sub folder will be used as a tag name. Some folders names like "PNG", "SVG", etc... will be ignored (so don't change the whole structure of your assets, we'll ignore anything that does not make sense). Note that you can also put assets in a folder called `Unimplemented` or `TODO`, and these folders will be entirely ignored.

For audio

Put your .aac or .wav files (prefer .aac) directly in a folder, with the name to be displayed: `Laser effect.aac`, `Background music.aac`. `TAGS.md` files will work like for images. Sub folders are also used for tags as described for images.

For fonts

Like images and audio, put your fonts in folders. `.ttf` and `.otf` files are supported. `TAGS.md` files will work like for images. Sub folders are also used for tags as described for images.

(⚠️ Advanced!) To make an object from scratch, for example particle emitters

These assets from scratch are a bit cumbersome to author right now. Here is an example folder that shows how the particle emitter objects from Wishforge Games are done: Particles.zip

Create an file with extension .asset.json, for example: My Particle Effect.asset.json. The format of this asset is:

{
  "id": "",
  "name": "",
  "authors": [""],
  "license": "",
  "shortDescription": "",
  "description": "Enter a description. Leave the rest empty, it will be autogenerated",
  "previewImageUrls": [],
  "tags": [],
  "objectAssets": [
    {
      "object": { ...JSON CONTENT OF AN OBJECT...  },
      "resources": [ ],
      "customization": []
    }
  ],
  "gdevelopVersion": "",
  "version": ""
}

Leave almost everything empty. Create your object in GDevelop, then copy it in the clipboard. Paste the content in a file, and then copy just the "content.object" key:

Paste it inside the .asset.json file you created, replacing ...JSON CONTENT OF AN OBJECT...:

Finally, if your object uses image resources, make sure to add them in the resources array:

Put all images with the name that you put in the resources array next to your .asset.json file.

Finally, add:

• a file with the same name but with the extension .preview.png that will be shown in the assets store
• an empty filed called IGNORED_FOR_IMAGE_ASSETS.md so that the importer will ignore the images and won't try to create objects automatically :)

For example:

License

Put a license.txt file in your folder. The importing will recognize it and apply to all files in the folder :)
Make sure to put your name in this license file too (or the name of the original author).
The importer will be adapted to understand the license file.

Something unclear?

Just ask me in this thread :) If the rules here are too complicated or are giving you too much work, you can suggest me a new rule and I'll see if I can adapt the importer so that it can understand your asset structure :)
The goal is to make objects more or less automatically!

How to send my assets when they are ready?

Zip the folder containing them and send them to @4ian, either by opening an issue here or by tagging @florianrival on a card on the GDevelop Assets Trello board: https://trello.com/b/xoOCKFOf/gdevelop-assets

[tristanbob]

How are we going to deal with file-name collisions? I am working on a large project now and have experienced the frustrating problem when you have two objects that use the same file name.

[arthuro555]

(⚠️ Advanced!) To make an object from scratch, for example particle emitters

Maybe we could add an option to export an object to the asset store format from the IDE in the future?

[4ian]

How are we going to deal with file-name collisions? I am working on a large project now and have experienced the frustrating problem when you have two objects that use the same file name.

It's handled by GDevelop itself. When an asset is added, GDevelop looks for all resources:

• is this a resource (i.e: an image/font/audio file) that was already imported from the asset store? If yes, don't download it again.
• otherwise, then it's downlaoded and if there is a resource already existing with this name, a new name is generated (basically a number is added at the end of the resource and file name: 2, 3, 4...). Of course, this means the imported object will also get its internal resource names updated.

In other words: no worries :) If there are 100 objects in 100 different folders that are all named "Player.png" (generating an object called Player), you'll still be able to search and import all of them without clashes - and without clashes with your own existing resources.

Maybe we could add an option to export an object to the asset store format from the IDE in the future?

Totally. By lack of time I've not added it already, but if someone wants to do that, it should be doable to have an option that would export the object in a .asset.json file, with the resource (images basically) next to it.

[tristanbob]

It's handled by GDevelop itself. When an asset is added, GDevelop looks for all resources:

Does GDevelop beta102 currently handle name collisions when importing assets? This is the second time I've run into this problem on this project.

[Entr0py404]

I'm trying to make it a bit easier for my self to make the files for the time being but is this the right format?
https://www.youtube.com/watch?v=XfVbTVCW8rs

Where is the description shown in the UI of GDev ?, I think I'm getting confused by the automatically generated ones.

"an empty filed called IGNORED_FOR_IMAGE_ASSETS.md so that the importer will ignore the images and won't try to create objects automatically"

What would be a example of when to use this?
Is it only for when making a asset.json?
Does the importer automatically ignore image files based on its existence?

The files I used had an extra underscore in them and don't contain the asset name, file names don't matter for asset.json right?
But probably should use the same naming conventions though.

[4ian]

I'm trying to make it a bit easier for my self to make the files for the time being but is this the right format?

This looks mostly correct!
Only thing I could spot is that the resource files in the json are have a relative path with a sub folder (NinjaAdventure/Slide___001.png, etc...) while they should be referred to without this sub folder (Slide___001.png, etc...).

Is it only for when making a asset.json?
Does the importer automatically ignore image files based on its existence?

Yes and yes. If you had a file called IGNORED_FOR_IMAGE_ASSETS.md, the importer won't try to automatically create object from the images found in this folder. It's only useful for your folder containing a .asset.json file

The files I used had an extra underscore in them and don't contain the asset name, file names don't matter for asset.json right?

Yes, there is no convention for the .asset.json file, but as with others the filename should be in plain English:
My Super Ninja.asset.json (will be used to create an asset called My Super Ninja). The name of the resource files (the images) are not important because they won't be used to create objects... but still try to use similar name/same convention so that the creator that uses the asset does not have weird file names in its resources :)

Does GDevelop beta102 currently handle name collisions when importing assets? This is the second time I've run into this problem on this project.

Can you post the steps to reproduce this? Thanks!

[tristanbob]

In this video, I start from a new project and add two sprite objects with multiple frames each. Source files for both objects have the same names, which GDevelop doesn't handle properly.

https://user-images.githubusercontent.com/8879811/103448259-34b25b80-4c54-11eb-9f96-3a0cd06e2d5b.mp4

[4ian]

@tristanbob Ok I see, this is not related to the assets store so let's continue the discussion on a new issue :)
There is no check for existing files made when you add a resource from another folder. The solution for now is to copy by yourself the images in your project folder.
The asset store does not have this issue as images are compared to existing resources :) To fix your specific issue, we would need when copying assets that are to be added from a folder outside of the project, to check the content of each overwritten file.