Skip to content
SplashKit

Contributing to Usage Examples

To contribute a function usage example, you need to create the following files:

  • Text file (.txt) containing a title and short description of the example.
  • Output Image/Video file showing the expected output of the example. This output file needs to be one of the following:
    • Image file (.png)
    • Gif file (.gif) if the example code is interactive
    • Webm file (.webm) if there is audio in the code example.
  • Code files with the example code. This must be a complete code example, not just a snippet of code.
  • Zip file (only if your code requires resource files) containing the “Resources” folder created with the skm resources command, with any resources needed for your example code to run. (More info about adding this at the end.)

File Location

Place the following files into the folder with the unique global name located in /public/usage-examples/<category folder of the function>:

  • The .txt text file.
  • The .cpp and .cs and .py code files.

eg. For the write_line examples mentioned below, these would be located in /public/usage-examples/terminal/write_line/.

File Naming

To allow the files to be used to automatically generate the usage example MDX page, you need to follow a specific format when naming your files.

Here is an example of files for two code examples added for the write_line function that are demonstrating the use of void write_line(string line);:

write_line-1-simple-oop.cs
write_line-1-simple-top-level.cs
write_line-1-simple.cpp
write_line-1-simple.png
write_line-1-simple.py
write_line-1-simple.txt
write_line-2-extended-oop.cs
write_line-2-extended-top-level.cs
write_line-2-extended.cpp
write_line-2-extended.png
write_line-2-extended.py
write_line-2-extended.txt

Breaking down the first line from above:

write_line-1-simple.cpp
    ^      ^    ^     ^
    |      |    |     |
    |      |    |     -----: file type: .cpp
    |      |    |
    |      |    ---------------: complexity identifier: simple
    |      |                     (can be "simple" or "extended":
    |      |                     - use "simple" for small targeted examples
    |      |                     - use "extended" for complex or fun/funny examples)
    |      |
    |      --------------------: number id of example: -1-
    |                            (used to separate examples regardless of "simple/extended" identifier)
    |
    ---------------------------: folder name: write_line
                                 (created using the "unique_global_name" key
                                 from SplashKit's "api.json" file)

File Contents

Text file

The text file needs to include:

  • Name of the example program, using a level 4 markdown heading, ####.
  • Short description of what the example code is demonstrating, with a hyperlink to the function’s API Documentation details.

Here is an example of the contents of the write_line-2-extended.txt file:

#### ASCII Art - Charlie the Unicorn


The following code is an example of using [Write Line](/api/terminal#write-line-5) to create ASCII art of "Charlie the Unicorn" in the terminal.

Output Image/Gif/Audio file

Add a screenshot of the output of the example program.

  • If the example program includes user input or any movement, please create a Gif showing the program running.
  • If the example program includes audio, please create a Webm file showing the program running. You can use a tool such as ffmpeg to convert your video files to .webm files.

Remove identifying details from the image/gif/audio where possible.

Code file(s)

Please follow the guidelines below:

  • All of the example code needs to be in a single file.
  • Example code should be able to be run by copying the code into an empty code file.
  • Make sure to include 4 code files:
    1. .cpp file
    2. .cs file using top-level statements style
    3. .cs file using object-oriented style
    4. .py file

Write Line Examples

For more info, you can look at the completed Write Line examples in the folder: /public/usage-examples/terminal/write_line/

Adding Zip File Resources

If you have created an example with specific image/sound/etc files, you will need to create and add a zip file containing this folder.

Zip file contents

Make sure that you have run the skm resources command, and put your resource files inside the relevant folder (eg. images).

Then compress/zip the “Resources” folder and give it a relevant name for when users download this file. (This should not follow the same naming conventions as the other files so that it has a nicer name for users.)

Linking to the Resources

In the text .txt file for your example, add a “note” callout at the end that links to the zip file using the following template:

:::note
To test this example code you can download these [**Resources**](/usage-examples/<category>/<unique-global-name>/<your-zip-file-name>.zip).
:::

Then update the link in the template above to add the <category>, <unique-global-name> and <your-zip-file-name>.

eg. For the first draw_bitmap_named example that has been created, the text file contents would look like this:

### Basic Bitmap Drawing


The following code shows an example of using [Draw Bitmap](/api/graphics/#draw-bitmap-3) to display a Bitmap image of the SplashKit logo in a graphics Window.


:::note
To test this example code you can download these [**Resources**](/usage-examples/graphics/draw_bitmap/DrawBitmap_BasicBitmapDrawingResources.zip).
:::