Creating packages

This is a tutorial on manually creating .arcpkg files for importing into mobile clients.

If you want to export .arcpkg manually through ArcCreate editor, see Exporting packages

For importing packages into ArcCreate player, see Importing packages

1. What's an .arcpkg?

An .arcpkg file holds data that can be imported into mobile ArcCreate clients. Not just levels, but you can also include level packs in an .arcpkg, and any other asset types implemented in the future will also be imported using .arcpkg.

Currently the PC editor can only export packages containing a single level, but you can manually create custom packages that contains multiple levels, or level packs. This guide explains how you can manually package your data to do just that.

Note: "Asset" refers to anything that can be imported into ArcCreate mobile client. This currently includes levels, and level packs

2. Anatomy of an .arcpkg

A valid package must contains the following

• A file named index.yml. This lists all available assets that can be imported within your package. See section 3 for more details
• Multiple folders, each folder containing data relevant to their asset type. For example, a folder for a level will contain an .arcproj file, music file, chart file, etc,... Details on the structure of each asset type will be discussed in section 4.

Here's an example of what your package might look like:

- firstLevel/
- secondLevel/
- levelPack/
- index.yml

3. index.yml

This files define everything that will be imported once players import your package. Anything that is not listed under index.yml will be ignored by the client upon importing.

As the file extension suggests, index.yml is a YAML file. You'll mostly be okay with writing with a template as a base, but you should use an editor that can highlight any syntax error for you. VSCode is good for this.

Here's what the content of the file looks like

- directory: firstLevel
  identifier: yourNaneHere.firstLevel
  settingsFile: proj.arcproj
  version: 0
  type: level
- directory: secondLevel
  identifier: yourNameHere.secondLevel
  settingsFile: proj.arcproj
  version: 0
  type: level
- directory: levelPack
  identifier: yourNameHere.levelPack
  settingsFile: pack.yml
  version: 0
  type: pack

As you can see, it's a list of 3 items, each with the same 5 fields.

• directory: The folder containing data for this asset. This should be the exact same as the folder name contained in the archived file. If you get this field wrong ArcCreate will not be able to find your files.
• identifier: The unique identifier of this asset. An ArcCreate client can NOT store two or more assets of the same type that's also the same identifier. Try to name this value so that you're sure players won't run into another asset somewhere else with the same identifier. The format recommended is: [publisher].[name], where publisher can be your name, or your team's name, and name is the name of the asset. pentachrome.villainvirus, zydekun.mobius, zeroth.iamend are examples of good identifiers. The purpose of identifier is for creating updated version of an asset. By using the same identifier on a different package, upon importing any asset with the same identifier that the player has already imported can be replaced with the new one, instead of having duplicate assets.
• settingsFile: The file name of the settings file for this asset. This file name will be combined with directory, so do not include it in this field unless you mean to. For example, for the first item, its directory is firstLevel, and its settings file is proj.arcproj, which corresponds to the file located at firstLevel/proj.arcProj. All settings file in ArcCreate uses the YAML format, regardless of the extension of the file. You can name these files however you like, the only important thing is to have the file itself be in the correct YAML format, and have the correct fields according to each asset type, and that it's referenced properly in index.yml
• version: The version of your package. When a player import an asset, if another asset that's already imported with the same identifier exists, then depending on the version of the two assets, the following will happen:
  • If the importing asset's version is equal to or larger than the asset that already exists in the storage, then the asset that's already in the storage will be REPLACED with the importing asset.
  • Otherwise if the importing asset's version is smaller than the asset that already exists, then the player will be given the option to either replace with the importing asset (the same as above), or to not import the asset at all (make no change).
• type: The type of the asset. Refer to the following sections for more details.

4. All asset types

4.1. level

Contains data for a single level.

Settings file format: The same as .arcproj.

Folder structure: exactly the same as a project folder that's used by the PC editor, with a few differences:

• You don't have to use .arcproj as the extension of the metadata file (just reference the file properly in index.yml).
• If you use scenecontrol then [chart_file_name].sc.json must be included for scenecontrol to work at all. If chart uses scenecontrol then this file will be generated automatically whenever you save the chart.
• .lua scripts for scenecontrol are not required to be included in the package. They will not be run at all by the mobile client. Any image files and other assets used by scenecontrol is however, required to be included.

Example of a level asset folder:

- firstLevel
  - Scenecontrol
    - imageUsedBySc.png
  - proj.arcproj
  - base.ogg
  - base.jpg
  - 2.aff
  - 2.sc.json

4.2. pack

Contains data for a level pack. A level pack is essentially a way to group your levels up into a single list. Players can select your pack and see only the levels that are included in the pack.

Settings file: a YAML file with the following format:

packName: Pack name goes here
imagePath: packImage.png
levelIdentifiers:
  - yourNameHere.firstLevel
  - yourNameHere.secondLevel

• packName: The name of the level pack. This is displayed on the pack selection screen.
• imagePath: The path to the image file that will be used as the cover image for the pack. This is displayed on the pack selection screen. It's recommended size is 314px in width and 756px in height.
• levelIdentifiers: The list of identifiers of levels included in this pack. Note that players don't have to import all the levels listed here. If there are identifiers listed that doesn't have a corresponding level that's already been imported by the player, then it will simply be ignored. The player can import the levels after the pack has been imported and it will be recognized.

Folder structure: Contains the settings file and the image file used as the pack cover.

4.3. character

Contains data for a character. A character currently only represents a still image that appears on the result screen.

Settings file: a YAML file with the following format:

name:
  default: Default character name
  ja-jp: Character name in japanese
  ...
imagePath: characterImage.png
iconPath: iconImage.png
x: 0
y: 0
scale: 1

• name: Describes the name of the character in different languages. default is used if the user's selected language is not included in this property. Otherwise, the name matching the selected language code is used. See [https://github.com/Arcthesia/ArcCreate/blob/master/Assets/StreamingAssets/locale_list.yml](this file) for the list of languages available in ArcCreate.
• imagePath: The path to the full image of the character. There are no restriction on file size or aspect ratio, ArcCreate will resize it automatically.
• iconPath: The path to the icon image of the character. Currently unused. A square image with transparent background is recommended.
• x: Horizontally offsets the location of the character image in the result screen.
• y: Vertically offsets the location of the character image in the result screen.
• scale: Scales the character image in the result screen up or down.

5. Packaging your .arcpkg After creating all necessary files and writing all the necessary settings, it's time to create the final package.

Select all the folders and file to be included in the package and archive them as a .zip file.

A few common mistakes:

• Do not archive them as any other format like .7z, .rar, etc. Only use .zip.
• Do not compress the parent folder of the files to include. After you unzip your file you should immediately see index.yml.

That's it, rename your package to use the extension .arcpkg, and it's now ready to be imported into ArcCreate.