Guide to the Renpy Sprite Creator

Tags: posts, tutorial, renpy, renpy sprite creator, my games, from dreamwidth,

Note: This tool has largely been superseded by the Visual Novel Sprite Creator.

Contents:

About This Creator:

This is a guide to the Renpy Sprite Creator from Spiral Atlas Games, a tool for creating sprites for Renpy and other Visual Novel programs. It is no way officially affiliated with the Renpy engine, it's just designed for use within Renpy games.

Download the latest version of this tool at https://spiralatlas.itch.io/renpy-sprite-creator. Please contact me there if you need help, hit a bug, or have suggestions for later releases.

Although this tool is primarily intended for Renpy developers, it's possible to create flat sprites that could be used in other visual novel engines, as described in the section "Working with other Visual Novel engines".

The contents of this tool are released under a Creative Commons license, including the art and code, and can be used for commercial works. Creative Commons License
Renpy Sprite Creator by Spiral Atlas Games is licensed under a Creative Commons Attribution 4.0 International License.
Based on a work at https://spiralatlas.itch.io/renpy-sprite-creator.

Images and sprite_scale

The images are all saved as 428x1200 pixel black and white pngs in the spritecreator_images folder, with names of the form: 
pix_{imagetype}_{imagename}.png
So for example, pix_hat_crown.png is a picture of a hat, specifically a crown. It's within the /spritecreator_images/clothes/hats folder.

You don't have to remember these names, since the dollmaker will pick them out for you.

The tool creates sprites by colouring and layering these images, then scaling and cropping them.

Each sprite's size is defined by two dimensions: the floor and the size. The floor is how many pixels the sprite is cut off above it's feet, and the height is how many pixels tall it is once cropped. This includes the empty space above the sprite's head.

The sprite_scale(floor,height) transform resizes any 1200 pixel image into a {height+floor} pixel tall image, then crops off the bottom {floor} pixels, leaving a {height} pixels tall image.

The default dimensions are a floor of 200 and height of 750.

Simple sprites in black and white

The code defines a pix layeredimage sprite which just uses the black and white images in their unedited form. It's 1200 pixels high, so to create a useable black and white sprite of a custom height, create a proxy, eg:

image pix_sprite = LayeredImageProxy("pix", sprite_scale(200,750))

is 750 pixels tall, with the bottom 200 pixels cut off.

If you want to show this sprite wearing a crown, call it like so:

show pix_sprite crown

and Renpy will automatically know to use the image pix_hat_crown.png for the sprite's hat. Unfortunately there's many repeated image names so this sprite is best used if you want something featureless but simple.

The Dollmaker

The dollmaker lets you create coloured, patterned, resized sprites with a variety of outfits, bodies, and expressions, and returns the code required to call them from within your renpy project.

Basic instructions for using the Dollmaker to create sprites

  1. Have a Renpy project ready to put the sprites into. Place a copy of the /spritecreator_images folder within your project's /images folder, and a copy of the /spritecreator_scripts folder within your project's /game folder.

  2. Open the Renpy Sprite Creator game. Click through to the dollmaker.

  3. Tweak the settings until you like the look of your sprite.

  4. Select "Copy Body/Outfit" to copy your sprite's code to the clipboard. Paste this code into a text editor.

  5. If you want to create custom expressions: Select "Copy Expression" to get code for each specific expression. Paste the relevant line of this into the emotion section of the base code, either overwriting an existing emotion or creating a new one.

  6. Do a search and replace for temp_name, changing it to the name of your character.

  7. Post this code into your Renpy project.

You should be able to use your sprite!

Note: Using a lot of sprites with patterns or extra items may make Renpy run slowly or crash. If using dollmaker sprites slows your game down too much, use simpler sprites, or use the python script described below to create flattened images.

Doll maker details

General:

On the left-hand side of the screen is an image of the current doll being edited.

On the right-hand side of the screen is the editor window, showing the Body Editor, Outfit Editor or Expression editor.

These screens allow you to edit the properties of the different parts of the sprite: Style: The style/shape/kind of item Colour: the fill colour Line: the line colour Pattern: The pattern P. Colour: The pattern colour

See The parts of a sprite for a description of each part.

The Style and Pattern buttons cycle through all possible options, including "none".

The colour/linecolour/patterncolour buttons lead to the colour picking screen.

Some items are edited as a group, eg the front, middle, and back parts of the hair are automatically given the same colour/linecolour/pattern/patterncolour.

Below the editing options are buttons to navigate between the Body Editor, Outfit Editor and Expression editor. There's also a Randomise button, which randomises the options on the screen, and the Settings button.

Below that are the copying buttons:

Copy Body/Outfit: The code for the current doll, with default expressions happy, sad, kinda_happy, kinda_sad, afraid, flirty, surprised, angry. This includes the code for the default face colours.

Copy Expression: The code for the current expression: eyebrows, eyes, cheeks, and mouth. Includes the current face colours, which can be either used or ignored depending on which line of code you use.

Done: Quit the doll maker.

Colour Choice Screen

This screen displays the current colour for whatever is being edited on the palette and on the bottom of the screen. If you have trouble seeing colours, pressing V will turn on self voicing, which includes simple colour descriptions.

There are two palettes: a broad spectrum of colours organised by hue, and a more restricted set of small palettes with harmonious colour schemes. The harmonious palettes are designed for creating harmonious outfits.

Switch Palettes: Switches between the spectrum of colours, and the set of harmonious palettes.

Body Editor: Edit the skin and hair

Dimensions: the floor and height of the sprite. Actual Size/Full Body: whether to show the sprite's real size, or scale it to show the entire body onscreen.

Skin: set the colour/line/pattern/patterncolour for the head and body. Styles are set individually below.

Hair: set the colour/line/pattern/patterncolour for the hair. Styles are set individually below.

Ears: All the ear settings. The "Match Body" button matches the colour/line/pattern/patterncolour to the head and body.

Head/Body: set the style

Nose: Set the style and colour. Note that the line colour is the same as the head and body, but the fill colour can be different. This only matters for animal type noses.

Hair back/Hair middle/Hair front/Facial Hair: set the styles of all the different parts of the hair.

Outfit Editor: Edit the clothes and accessories

"Dec" is short for decoration.

Note that while the dollmaker only allows one of each item, displayed in a set order, you can add extras or change the order in the code.

While most of these are clothes, there's also a few body parts: wrinkles and freckles in the "Face Dec" section, tails in the "Back" section, and breast shape outlines in the "Torso Dec" section.

Expression editor: Edit the eyebrows, eyes, cheeks, and mouth

The expression is controlled separately from the rest of the doll: while the body and clothes stay the same, the eyebrows, eyes, cheeks, and mouth change with different emotions.

None of these parts can have patterns added.

The eyes consist of two parts, each with their own colours: First is the iris. In front of that is the eye_shape, which is the eyelashes, pupil, and sclera/whites. Not all eye_shape styles have a visible iris.

Eyebrows: these just have a shape because their lines are set by the face lines, and none of the current eyebrow art has a visible fill colour.

Eye shape: The shape and fill colour of the eyes. Controls the iris shape automatically.

Iris: The line and colour. The "line" colour affects the shade of the shadow at the top.

Mouth: just a shape because the lines are set by the "Face" linecolour. Some of the mouth styles can look odd with anything but red or black lines. You can edit the fill colour in the code but it might look strange.

Face line colour: sets the line colour for the eyebrows, eye lines, and mouth. These can all be set separately in the code.

Settings

The Settings screen has three options:

Colour Randomness: This controls how restricted the colours are when you randomise the options on a screen.

  1. Realistic: human-plausible skin/eye/hair colours, ears match the face, outfit colours chosen from the set of pre-defined palettes. Line colours are matched to the fill colour. There's a few other limitations, like always having a head.
  2. Tastefully Creative: skin/eye/hair can be any colour, but sclera of the eyes are white. Outfit colours are randomly generated but within palettes that use similar or complimentary colours. Line colours are matched to the fill colour.
  3. "No LIMITS" chooses colours and linecolours entirely at random.

Line Colours:

  1. Automatic: Line colours are chosen by the software to match the fill colour (darker for light colours, and lighter for dark colours)
  2. Custom: Line colours are left to the user to choose.

Accessibility:

  1. Self Voicing: Allows the user to turn on self voicing, which canm also be achieved by pressing 'v'.
  2. More Options: links to Renpy's in-built accessibility menu.

Code Structure

So! You've made a body/outfit you like, and copied the code to a text file, along with code for all the different expressions you want for your sprite. If you're happy with the sprite as it is now, you can stop there. But if you want to tweak it, you'll need to understand how the code works.

To understand this section you'll need a moderately good grasp of Ren'py and LayeredImages. Check out https://tofurocks.itch.io/renpytut-layeredimage for a good introduction.

Basic Structure

The code is divided into several parts.

First is an init block that defines the face colours. It's of the form:

init:
    # [iris shadow colour, iris fill colour, eye linecolour, eye fill colour, 
       cheek line colour, cheek fill colour, eyebrow line colour, eyebrow fill colour,
       mouth line colour, mouth fill colour]
    $ {name}_facecolours = { whatever the face colours are }

The dollmaker outputs face colours where the eye linecolour, eyebrow line colour and mouth line colour are all the same, but you can edit them here if you want. The cheek fill and eyebrow fill colours don't have any effect on the current art for those items. The mouth fill will look weird as anything but white but you can still edit it if you want.

Next is the actual image definition. It starts:

layeredimage {name}:

    at sprite_scale({floor},{height})

which gives the name, and transforms/crops it to have the right floor and height respectively.

Now to show all the parts of the sprite, from bottom to top.

First are all the items below the face. These involve calls to show_item and show_item_pattern, as defined below.

Then come the expressions:

group emotion:
        attribute {feeling1}:
            show_expression( parts of the face )
	attribute {feeling2}:
            show_expression( parts of the face )
            ...

Then come all the items above the face, which again involve calls to show_item and show_item_pattern.

You can rearrange the order of the items but it may look odd.

The parts of a sprite

From back to front:

Functions

Colours are in hex format. Here's an explanation for how hex codes work: https://www.pluralsight.com/blog/tutorials/understanding-hexadecimal-colors-simple

If you paste a hex code into a colour picker you can see what colour it is: https://www.google.com/search?q=color+picker

But most of the time you can just use whatever colour the dollmaker spits out without worrying about it.

Here's some example colours to get started:

#000000: black
#FFFFFF: white
#ff0000: red
#00ff00: blue
#0000ff: green

Here are the main functions that show up in sprites made using this tool:

sprite_scale(floor,height)
eg sprite_scale(100,800) is a 800 pixel tall sprite with just the bottom
100 pixels of it's legs cropped off.
There are two functions for showing an item of clothing or part of the body. The first just has flat colour:

show_item(item_type, item, linecolour, colour)
eg: show_item("hat", "crown", "#00000", "#FFFFFF") shows a white crown lined in black.
If you want to add a pattern, use:

show_item_pattern(item_type, item, linecolour, colour, pattern, patterncolour)
eg: show_item_pattern("hat", "crown", "#00000", "#FFFFFF","polkadots", "#ff0000")
shows a white crown lined in black with red polkadots.
There is one function for showing an expression:

show_expression_full(eyebrows, eye_shape, cheeks, mouth, colours)
where colours = { iris shadow colour, iris fill colour, eye linecolour, eye fill colour,
cheek linecolour, cheek fill colour,
eyebrow line colour, eyebrow fill colour,
mouth line colour, mouth fill colour}
eg: show_expression("none", "halfclosed", "blush", "shout",
{"#000000", "#ff0000", "#0000ff", "#FFFFFF","#00ff00",
"#00ff00","#0000ff", "#FFFFFF","#0000ff", "#FFFFFF" })
shows an expression with no eyebrows, halfclosed red eyes with white sclera,
blue blush, and a shouting mouth. All the lines are green.
That's a lot of colours to keep track of, but the dollmaker provides a variable called {character_name}_facecolours you can just substitute into expressions. The dollmaker makes the eyebrow and mouth lines match the eye_shape, but you can change that in the code.

The dollmaker outputs items in a specific order, but you can rearrange them or add extras.

Examples

All of these sprites are in the "spritecreator examples.rpy" file, and the Sprite Creator game. If there's a character in the game whose code you're curious about, look up it's name in the script. Here's a few instructive examples of increasing complexity.

Consider the wizard sprite. It starts with:

init:
    # {iris shadow colour, iris fill colour, eye linecolour, sclera colour, 
       cheek line colour, cheek fill colour, eyebrow line colour, eyebrow fill colour,
       mouth line colour, mouth fill colour}
    $ wizard_facecolours = {"#00004f", "#cf7fcf", "#2b230f", "#ffffff", "#ff9f9f", 
                            "#ff9f9f", "#2b230f", "#ffffff", "#2b230f", "#ffffff"}

which are the colours chosen in the dollmaker. Since I'm not messing with them, I can ignore them.

It's at sprite_scale(200,750), which is about average size.

Next comes the back of the coat, and short curly hair, then in front of that are the ears, body, and head, with colours as picked in the dollmaker.

The expression code is just:

group emotion:
        attribute blep:
            show_expression("regular","wink","blush","blep", wizard_facecolours)

which is regular eyebrows, winking eyes, blushing cheeks, and a mouth with a tongue sticking out, using the colours from wizard_facecolours.

In front of the face is the nose, glasses, shoes, etc. Note that there's two "front" items, even though the dollmaker only lets you pick one of each item type:

always show_item_pattern("front","scarf","#00001f","#575757","horizontalstripe","#000027")
always show_item_pattern("front","scarfwrap","#00001f","#575757","horizontalstripe","#000027")
How I created this code was I made one version of the wizard with the scarf style of front in the colours I wanted, and used that as the base. Then I changed the front style to the scarfwrap, and picked those colours, then copied the new code to another text file. I cut and pasted the line of code for the scarfwrap into the first file.

Also the shirt top has been shifted in front of the trousers bottom to look a little messier.

Now consider the goth:

init:
    # {iris shadow colour, iris fill colour, eye linecolour, sclera colour, 
       cheek line colour, cheek fill colour, eyebrow line colour, eyebrow fill colour, 
       mouth line colour, mouth fill colour}
    $ goth_facecolours = { "#5f005f", "#379ddf", "#000000", "#ffffff", 
                           "#ff5f5f", "#ff5f5f", "#ebdb57","#ffffff", "#cf0000", "#ffffff"}

This sprite has different colours for the eyebrow lines (yellow), eye linecolour (black), and mouth (red). I made three versions of the sprite and copied the body/outfit code each time, then pasted the relevant colours in the right places.

Then the emotions just use the goth_facecolours variable: 

group emotion:
attribute meh:
show_expression("regular","narrow","none","dubious", goth_facecolours)
attribute kinda_happy:
show_expression("regular", "narrow","none","smallsmile", goth_facecolours)
The "half" pattern, which covers the left half of the image in a flat colour, allows for one red glove and one black: 
always show_item_pattern("gloves","fingerless","#000000","#bf0000","half","#000000")
Now consider the demon sprite. It is the only example sprite not to have it's floor set to 200 pixels:

layeredimage demon:


at sprite_scale(0,500)
Instead, the floor is set to 0 pixels, which means the feet/legs aren't cropped at all. But the height is only 500 pixels, which is much less than the usual 750. So it's tiny with visible feet. You could also add a transform here to make it hang in the air and move about, but I did that via a custom transform in the script instead.

It has different eyecolours depending on it's expression, so they have to be included in each emotion separately:

group emotion:
       attribute mean_smile:
           show_expression("angry","narrow","none","bigsmile", 
                 {"#eba45e", "#000", "#632315", "#cc1414","#264a2f","#264a2f",
                  "#632315", "#cc1414","#632315", "#cc1414"})
        attribute tsundere:
            show_expression("angry","narrowsideeye","blush","pout",
                 {"#000", "#eba45e", "#632315", "#eba45e","#264a2f", "#264a2f",
                  "#632315", "#eba45e","#264a2f", "#eba45e" })

Using the layered image files

The itchio page for this project has two layered image files available for download:

One is in Clip Studio Paint format (clip) and one in Photoshop format (psd). The Clip Studio Paint file has vectors, but can only read by the Clip Studio Paint program.

If you don't have a copy of Clip Studio Paint, psd files can be read by most image editing programs, including free programs like GIMP and FireAlpaca.

I'm not going to go into how to use image editing software, but it should be possible to approximate any sprite created in the dollmaker using these images, and they can be used as a base for your own art.

The Python Script

There is a python script called generate_images.py which can be used to create images from the code outputted by the dollmaker. The sprites it creates load much faster, and have much simpler renpy code. It's a little janky and will break if you mess with the dollmaker code too much, but should work for the kinds of edited sprites given in the examples.

To run the script, you need to have a copy of Python installed, as well as the extension Pillow. The current version of the generator was made to run with Python 3.9.1

Download Python: https://www.python.org/downloads/ Install Pillow: https://python-pillow.org/

Before you run the script, paste the renpy code for a single sprite into the sprite_code.rpy file. Use a name that doesn't conflict with any existing sprites.

To run the script, open a terminal window (Mac or Linux) or command line (Windows). Navigate to this renpy project, then navigate to the python_script folder, Sprite Creator/game/python_script

Type python generate_image.py at the prompt and wait until it's complete. This should only take a few seconds.

A file called {name}.rpy will be created within the /generated_renpy folder. Images named {name}_back.png, {name}emotion{feeling1}.png, {name}emotion{feeling2}.png etc, and {name}_back.png will be created within the /generated_sprites image folder inside /images.

The code needs to use the following structure, matching the output of the dollmaker:

init:
    $ {name}_facecolours = { 9 colours in hex format}

layeredimage {name}:

    at sprite_scale({floor},{height})

    {a list of uses of create_item and create_item_pattern for the items behind the face}

    group emotion:
        attribute {feeling1}:
            create_expression({details})
	attribute {feeling2}:
            create_expression({details})
	...

    group cheeks:
        attribute blush:
            create_item("cheeks","blush",{cheek colour}, {cheek colour})

    {a list of uses of create_item and create_item_pattern for the items in front of the face}

The face colours for each emotion can be given as a list of nine colours, or just the variable {name}_facecolours. All the emotions have to be in one block, but otherwise the script doesn't care what order things are listed in.

If you use these generated images, you don't need to copy across the /spritecreator_scripts or /spritecreator_images folders into your project, just the relevant images from /generated_sprites and code from /generated_renpy.

This script only recognises comments which start with a # symbol and include the whole line. It will get confused if you put more than one sprite's code in the sprite_code.rpy/ file.

Adding your own images and textures to the dollmaker

Adding an image to an existing part of the dollmaker is pretty straightforward.

Any image should be in black and white, and any clothing/body item should have black lines and white fill. Look at the existing images to get an idea. Choose a short, informative name.

I'll use the example of a texture called spades.png.

  1. Save a copy of your image in the relevant folder of images/spritecreator_images. Follow the naming structure of the other images, pix_{imagetype}_{imagename}.png. So for example, we would go into images/spritecreator_images/pattern and save the file as pix_pattern_spades.png.

  2. Go into /spritecreator_scripts/shared_python.rpy. Scroll down to the section that starts with "## Initialise all the clothing etc lists" and add the base name of the image to the relevant list. So for example, we would add "spades" to the pattern_list list.

And now the image should show up in the dollmaker!

Working with other Visual Novel engines

The process for creating sprites for other engines is pretty similar. But here's a summary that minimises the amount of Renpy coding. You'll need to install Python and Pillow as described in the previous section.

  1. Open the Renpy Sprite Creator game. Click through to the dollmaker.

  2. Tweak the settings until you like the look of your sprite.

  3. Select "Copy Body/Outfit" to copy your sprite's code to the clipboard. Paste this code into a text editor.

  4. OPTIONAL: If you want to create custom expressions: Select "Copy Expression" to get code for each specific expression. Paste the relevant line of this into the emotion section of the base code, either overwriting an existing emotion or creating a new one.

  5. Do a search and replace for temp_name, changing it to the name of your character.

  6. Paste this sprite code into the sprite_code.rpy file.

  7. Run python generate_image.py in a terminal window from Sprite Creator/game/python_script.

  8. Take the sprite images from the /generated_sprites image folder inside /images and use them in your project.

  9. To display the character {name} experiencing expression {feeling}, combine {name}_back.png, {name}emotion{feeling}.png and {name}_front.png in that order.

If this process breaks for some reason, let me know, and if neccesary I'd be happy to generate your images for you based on sent renpy code.

Using the dollmaker code for your own projects

I don't have instructions here because it depends on what you're doing with it, but it should be possible to adapt the dollmaker code to create a character creator for your game, either using my images or making your own.

Some of the alt text code may quietly break if you change things, make sure to test with self-voicing enabled (press "v") to know the program still runs for people using screenreaders.

Check if rollback works, I have had trouble with that and dollmakers in the past. Go to top