KP's Homepage

Grape's Adventure Mapping Information

Grape's Adventure

Grape's Adventure Deluxe is a game I've been working on to get myself out of my comfort zone and release something outside of a game jam. It's a vastly improved remake of my 2019 #icantdraw jam entry.

The game is written in C++17 using KP3D, the 3D engine you might've seen on my homepage.

The Mapping Tools

Maps for the game are made using this shitty editor I wrote in Java back in 2015 or so, albeit with new features added such as layers, a new file format, etc.

Map Editor SwineTech Vineyard Edition displaying a basic map for testing physics

User Interface

The way the editor works is very simple. You can create, delete, sort, and rename layers using the window on the far right. You can select the sprite for the tile you're about to place down using the window in the top right. There's a log in the bottom for viewing your edit history, and below that is a status bar showing you what's going on. There's also a mod player, but we won't talk about that.

In the map preview window, you can move around with WASD and hold shift to make the camera move faster. You can place tiles with MOUSE1 and remove them with MOUSE2.

The ID System

Every tile has an ID to make it clear to the game how that tile is supposed to function. So a tile with ID 1 for instance may be a normal solid tile, a tile with ID 2 may be a slope, etc.

The spec isn't final as the game is still in development, and the editor will be modified later on to make this more clear, but it should look something like this:

ID    | Description
0     | Non-solid (rarely used, since empty tiles act the same way)
1     | Solid
2     | 45° slope
3     | 135° slope
...   |
50    | Spawn bee
51    | Spawn cat
...   |
255   | Empty tile, reserved

You can change the ID of the tile you're about to place using the scroll wheel.

File Format

When making content for Grape's Adventure, there's 3 types of files you're gonna be dealing with.

WINE Exporter You can access this in Tools > Wine Editor

Yeah, this system is a little convoluted, but most of that is thanks to how old the editor is. This is the price you gotta pay when you write your own stuff; if you don't want the game to take an eternity to complete, reuse everything you got.

The tool you're looking at above is the WINE Editor, this is basically where you get to "direct" the game. You get to add maps, control the order maps appear in, setup events based on the win/lose condition of certain maps, trigger cutscenes, edit dialogue, switch game states, etc.

The way adding maps works is basically the same as layers, you hit + to add them and - to delete them. When you go to add a map, a file picker dialogue will appear. Both .WMAP and .SWINE files are accepted, because of this you'll almost never need to export .WMAPs from the editor.

WEXP Information

Once your map has been added, you'll need a way for the game to know how/when to use it. This is where WEXP comes in. WEXP information (meaning [W]ine + [Exp]erience) is basically responsible for the "directing" stuff I mentioned above.

The syntax is super simple, every line contains a single operator and a single operand. Here's what each operator does (subject to change):

Operator | Description
#        | This is a comment (ignored)
$        | This is a gamestate trigger (goes to the title screen, pause menu, etc.)
:        | This is a label
@        | This is a goto/unconditional jump
~        | This is a map (forces the gamestate to change to the main one)
`        | This is a map that changes behavior based on the win/lose condition
         | (used with the two operators below)
a        | This is a conditional jump operator
b        | Same as above, but for the opposite condition
"        | This is a piece of dialogue, speaker's name goes right after      
         | (All subsequent lines until one starting with the operator below contain
         |  text pertaining to the dialogue)
/        | This ends a piece of dialogue
*        | This is a misc. trigger, the game can figure out what to do with this 
         | from the operand (maybe for scripting in the future?)

It might seem a bit complicated at first, but this gives the game a lot of versatility. This makes modding and development way easier all around. If you wanted to playtest a single map for instance, you can skip all the cutscenes and dialogue without ever having to resort to modifying the actual game code.

WEXP Examples

The progression of Grape's Adventure 1 (the jam version):

$ menu
$ opening_cutscene
~ map0
~ map1
~ map2
~ map3
$ ending

A game containing a map where if you win, the game continues, but if you lose, the whole game restarts. Using conditional jumps:

: start
~ map0
~ map1
` roulette0
a continue
b start
: continue
~ map2
~ map3

A more arcade-like experience that just loops indefinitely:

: arcade
$ title_screen
: play
` map
a play
b lose
: lose
$ game_over
@ arcade

Character dialogue:

~ da_boat_race
" Chase
Heh, think you can beat me?


Q: How do I get rid of this horrendous starfield?
A: Change the map's background color to something else. Unintuitive, I know.

View > Set Background Color...

Q: What does Tools > "Edit metadata" do?
A: This is an old feature from the 2015 editor, it's useless for Grape's Adventure unless you want to add easter eggs or development notes to your .SWINE files.

Q: Why is it called SwineTech?
A: This version of the editor (titled "SwineTech Map Editor (Vineyard Edition)") is based off the editor for a continuation of Shibbal the Pig, another jam game of mine. The engine that game used was called "SwineTech", so the editor was named accordingly.

Q: Why should I care?
A: I don't know. I just needed somewhere to put the documentation for this.