How making SMC packages works

This article is not meant to replace the guidelines given in the How to Make Levels Repository-Compatible article in the SMC wiki, but rather to make some notes how levels, graphics, etc. should be designed to be directly usable by smc-get build.

Beta notice

This article refers to a not-yet released version of smc-get. The information given herein may get outdated as development goes on.

Choose your mode

First, you need to know smc-get build can be used in two different mannors: The interactive mode and the noninteractive mode.

Interactive mode

To run smc-get’s interactive mode, just issue

$ smc-get build

on the commandline. smc-get will then ask you all kinds of questions about your package, such as where the levels, graphics, etc. are located, how you want to name your levels, etc. Answer the questions carefully, and you’ll end up with a ready-to-distribute SMC package in your current working directory. There isn’t much to say about the interactive process, as it’s pretty self-explaining—but note, that smc-get looks into some folders on your computer to find out which file you meant when entering a level, graphic, sound or music file (or world directory): If you give it an absolute filename (such as /home/freak/mylevels/cool_level.smclvl or C:\mycoollevels\cool_level.smclvl, smc-get will not do anything with it and just use the file/directory you pointed to. But if you pass a relative filename instead (such as mylevel.smclvl or pixmaps/contrib-graphics/something.png, smc-get will do the following to find your file/directory:

1. Look into your personal SMC directory, i.e. ~/.smcget and try to dereference the relative path from there
2. Look into your SMC installation’s directory, e.g. /usr/share/smc and try to dereference the relative path from there.
3. Provide you with an error message if nothing could be found.

For example, if you put your graphics inside the /usr/share/smc/pixmaps/contrib-graphics folder (which is the folder where smc-get installs any graphics into), your levels will work in both your development environment and the user’s environment without you having to change the level to reflect graphics living in the final level elsewhere than in your personal environment. You can then just answer smc-get build’s question for your graphic with

> pixmaps/contrib-graphics/mygraphic.png

and it will find the graphic mygraphic.png in your SMC installation’s contrib-graphics folder.

Noninteractive mode

If you find yourself building the same package over and over again, the interactive mode can be a pain as you have to provide the exact same (or slightly changed) filenames again and again. This is where the noninteractive mode comes in handy.

Before you can invoke smc-get you have to prepare a directory whose structure matches the one used inside the SMCPAKs itself—smc-get will validate your directory against the packaging guidelines and will fail if something is wrong.

The basical structure of this directory is like this:

pkgname/
  - pkgname.yml
  - README.txt
  pixmaps/
  levels/
  music/
  sounds/
  worlds/

The toplevel directory, which is the one you pass to smc-get, should be be named as you want your package to be named—this name isn’t allowed to contain any whitespace. The package specification file’s (pkgname.yml in the above listing) name has to match the toplevel directory’s name exactly, otherwise smc-get will complain about a missing package specification.

Place your levels, graphics, etc. in the appropriate directories (you can use subfolders if you want to, except in the levels/ and worlds/ directories where SMC itself doesn’t recognize them) and then write the package specification. It doesn’t make sense to repeat everything the SMCPAK specifaction says about how to write a spec, so have a look at it if you don’t know how to write a package spec: https://github.com/Luiji/smc-get/blob/release-0.3.0/smcpak.rdoc (scroll down to section 8 “Specification format”). You may also read the SMCPAK specification entirely, it may be useful for creating SMCPAKs.

When your’re done with your directory, it’s time to invoke smc-get:

$ smc-get build yourdirectoryhere

Replace yourdirectoryhere with the appropriate directory and watch smc-get packaging and compressing your SMCPAK. If anything goes wrong, smc-get will inform you.

Where files are placed

As you have seen, the SMCPAKs contain paths like levels/, music/, etc. When a package is installed by smc-get install, the files contained in these directories are copied to your SMC installation into a folder called contrib-<something>/, where something is music, graphics, etc with two exceptions: Neither levels nor worlds are allowed to reside in subdirectories (restriction by SMC itself), they therefore reside directly in the usual folder. To clarify, if you have a package like this:

mypackage/
  - mypackage.yml
  levels/
    - level1.smclvl
    - level2.smclvl
  pixmaps/
    - graphic1.png
    - graphic2.png
    blocks/
      - cool_block.png
  sounds/
  music/
    - my_music.ogg
  worlds/

Then smc-get install will copy the files as follows (smc is your SMC installation path):

mypackage.yml ---------> smc/packages/mypackage.yml
level1.smclvl ---------> smc/levels/level1.png
level2.smclvl ---------> smc/levels/level2.png
graphic1.png ----------> smc/pixmaps/contrib-graphics/graphic1.png
graphic2.png ----------> smc/pixmaps/contrib-graphics/graphic2.png
cool_block.png --------> smc/pixmaps/contrib-graphics/blocks/cool_block.png
my_music.ogg ----------> smc/music/contrib-music/my-music.ogg

Please note that this applies to backgrounds as well. So, if you want to use your awesome hand-drawn background PNG file, you should put it into smc/pixmaps/contrib-graphics/background/my_background.png and point your level to that file. Then, when creating a package using the noninteractive mode, copy it into a folder called background inside the package’s pixmaps folder.

Keep these installation facts in mind when designing levels, otherwise you (or your users) will be quite surprised that their SMC can’t find the graphics/music/whatever you specified.