172.17.0.1: Style: no em dashes; Shop keeps only shop-scoped pity info

2026-07-05T01:24:08Z

Style: no em dashes; Shop keeps only shop-scoped pity info

Show changes

172.17.0.1: Match image display sizes to the source document

2026-07-05T01:03:17Z

Match image display sizes to the source document

Show changes

172.17.0.1: Add the original guide's 57 screenshots (hosted as extension assets)

2026-07-05T00:53:48Z

Add the original guide's 57 screenshots (hosted as extension assets)

Show changes

172.17.0.1: Adapted from VirtuaVirtue's Downwell Modding Documentation, with decompilation findings

2026-07-05T00:46:30Z

Adapted from VirtuaVirtue's Downwell Modding Documentation, with decompilation findings

New page

''Downwell'' is a GameMaker game, and nearly everything about it — sprites, code, sounds — lives in a single <code>data.win</code> file that can be edited with '''UndertaleModTool'''. This page is adapted from [https://docs.google.com/document/d/1bjOP715lMkC5dbPnMfEyhSGs4RvKaqw-OcRUvz6Co_8/ VirtuaVirtue's Downwell Modding Documentation], with additions from this wiki's own decompilation notes.

== Tools required ==

* '''[https://github.com/UnderminersTeam/UndertaleModTool UndertaleModTool]''' — the only tool you strictly need. Download a ''Stable'' release ("Bleeding Edge" is newer but less stable).
* '''Any pixel-precise image editor''' — Paint.NET, Aseprite, even MS Paint.

The game data lives at:
C:\Program Files (x86)\Steam\steamapps\common\Downwell\data.win

'''Make a backup of <code>data.win</code> before editing — you are modifying the game itself.'''

== Tutorial: new upgrades ==

[[Upgrades]] are the items offered at the end of every level. They are the best starting point for modding: little to no coding knowledge required.

=== Sprites ===

Each upgrade is one sprite with two frames:
* '''Frame 0''' — the selection icon shown on the end-of-level choice screen. 24×24 pixels.
* '''Frame 1''' — the inventory icon shown in the corner once taken. 12×12 pixels.

Upgrade sprites use '''at most three colors''': red <code>#FF0000</code>, white <code>#FFFFFF</code> and black <code>#000000</code>. The game's palette shaders automatically remap them to the player's chosen [[Palettes|palette]].

=== Naming scheme ===

Name the files as frames of one sprite, e.g. for a "Knuckle Sandwich" upgrade:
sUgSandwich_0.png (large icon)
sUgSandwich_1.png (small icon)

UndertaleModTool imports numbered files as frames of the same sprite. Put them alone in a folder.

=== Importing ===

# Open <code>data.win</code> in UndertaleModTool.
# Run '''Scripts → Resource Repackers → ImportGraphics.csx''' and select your folder.
# Check that a new <code>UndertaleEmbeddedTexture</code> exists (a texture-loading warning at this stage can be ignored, or save and reload).
# Find your sprite in the ''Sprites'' section and check its properties — most importantly the '''origin must be 12×12''' so the icons align in the menu and inventory.

=== language.ini ===

All of the game's text lives in <code>language.ini</code> next to <code>data.win</code>. Add your upgrade's name to the <code>ugName</code> section — the last vanilla entry is <code>ugName22</code>. Entries for the other languages are optional, but without them those languages show a blank name and description.

=== The upgrade table ===

Search for ''upgrades'' in UndertaleModTool and open <code>gml_Script_scrUpgrades</code> under ''Code''. This script is the upgrade database: every upgrade in the game is a block of <code>global.ug</code> assignments, with <code>i += 1</code> between blocks (the index — without the increment you overwrite the previous entry).

{| class="wikitable"
! Field !! Meaning
|-
| <code>ug[i][0]</code> || Name (shown on the choice screen)
|-
| <code>ug[i][1]</code> || Copies currently owned — the game resets it; leave at 0
|-
| <code>ug[i][2]</code> || Sprite '''index'''. The first sprite a mod imports lands at index 741; add 1 per additional sprite
|-
| <code>ug[i][3]</code> || Description; <code>#</code> is a line break
|-
| <code>ug[i][4]</code> || Maximum copies obtainable. The pickers only offer an upgrade while <code>ug[i][1] < ug[i][4]</code> — vanilla entries with 0 here (Dumbbell, Super Charge, Sudden Fortune) are cut content that can never appear. Leave at 1
|-
| <code>ug[i][5]</code> || Price in gems — '''only read for the shop consumables''' (indexes 100–105); dead data for regular upgrades. Leave at 200
|-
| <code>ug[i][6]</code> || Japanese name
|-
| <code>ug[i][7]</code> || Japanese description
|}

Copy an existing block to the end of the list, keep the <code>i += 1</code> above it, and fill in your values.

=== Functionality ===

Search for ''pug'' (Player UpGrade) and open <code>gml_Script_scrIncrementPug</code>. It is one large <code>switch</code> over the upgrade index, run when an upgrade is taken. Add a <code>case</code> for your index at the bottom (the 24th item is <code>case 23</code> — indexes start at 0) and put your effect there.

== Tutorial: new styles ==

[[Styles]] are the characters chosen at the start of a run.

=== Sprites ===

A style needs a '''run cycle of 8 frames''' and an '''idle animation of 4 frames''', at 15×15 pixels, using the same three-color rule as upgrades. Name them so they don't collide with existing sprites, e.g.:
sprPlayerIdleCart_0.png … sprPlayerIdleCart_3.png
sprPlayerRunCart_0.png … sprPlayerRunCart_7.png

Import exactly as in the upgrade tutorial, then check the sprite properties — here the '''origin must be 6×6'''.

=== language.ini ===

Add the style's name to the <code>styleName</code> section — the last vanilla entry is <code>styleName4</code>.

=== Wiring it up ===

Four scripts, all found by searching ''style'':

# <code>gml_GlobalScript_styleInit</code> — declares each style's name and animation sprite indexes (index variable <code>s</code>, incremented per style like the upgrade table). Point the animation fields at your imported sprite indexes (double-click a sprite; its index is shown at the bottom right).
# <code>gml_GlobalScript_styleUpdate</code> — runs when a style is selected and sets the player's stats. Copy an existing <code>case</code> to the end and adjust. Vanilla <code>gunType</code> values are 0–6 (see the [[#Reference: weapon stats|weapon table]]).
# <code>gml_GlobalScript_styleSet</code> — declares the animations again; possibly never called, but add your style for good practice.
# <code>gml_Object_PlayMenu_Create_0</code> (search ''playmenu'') — increment <code>styleMax</code> by 1 so the menu shows your style.

=== Unlocking ===

A new style starts locked with no unlock condition. Either:
* add it to the unlock tables — an entry in <code>gml_GlobalScript_unlockGoalNum</code> (shifting the later indexes) and a <code>case</code> in <code>gml_GlobalScript_unlockNotice</code> — or
* cheat it open: in <code>save.ini</code> (at <code>C:\Users\<you>\AppData\Local\Downwell_v1_0_5</code>) set the <code>gems</code> field, your progress toward all unlockables, to something absurd.

== Reference: weapon stats ==

New weapons are added in <code>gml_GlobalScript_bStatInitLevel1</code> by copying an existing weapon's block. Increment <code>gunnum</code> (<code>gunnum += 1</code>) above every new weapon.

Most stats are arrays of two values: <code>[gunnum][0]</code> applies '''without gem high''', <code>[gunnum][1]</code> '''with gem high''' (typically slightly stronger).

{| class="wikitable"
! Stat !! Meaning
|-
| <code>bStatName</code> || Pickup name, quoted, usually capitalised — e.g. <code>"NOPPY"</code>
|-
| <code>bStatGunSprite</code> || Letter shown on the collectible: position in the alphabet minus one (11 = "L")
|-
| <code>bStatObject</code> || Bullet object index — 261 for MACHINEGUN/SHOTGUN/TRIPLE/PUNCHER/BURST/NOPPY, 260 for LASER
|-
| <code>bStatBulletSprite</code> || Bullet sprite index (LASER: 466 normal, 465 gem high)
|-
| <code>bStatSound</code> || Firing sound index (LASER: 20 normal, 21 gem high)
|-
| <code>bStatMuzzle</code> || Muzzle-flash sprite index (SHOTGUN: 603 normal, 602 gem high)
|-
| <code>bStatConRate</code> || Charge consumed per shot
|-
| <code>bStatRof</code> || Rate of fire — lower is faster; negatives appear to disable it
|-
| <code>bStatRecoil</code> || Vertical speed lost when firing
|-
| <code>bStatScreenShake</code> / <code>bStatScreenShakeDur</code> || Screen-shake strength / duration
|-
| <code>bStatDelayKill</code> || Unclear; rapid-fire weapons set 1
|-
| <code>bStatBurst</code> || Burst-fire flag; only SHOTGUN and BURST set 1
|-
| <code>bStatBurstRate</code> || Delay between burst bullets — lower is faster
|-
| <code>bStatBurstAmount</code> || Bullets per trigger pull
|-
| <code>bStatDamage</code> || Damage per bullet (MACHINEGUN: 9 normal, 15 gem high)
|-
| <code>bStatSpeed</code> || Bullet speed
|-
| <code>bStatAccuracy</code> || Random spread
|-
| <code>bStatPierce</code> || 1 = bullets pass through enemies/objects while damaging them (LASER)
|-
| <code>bStatWave</code> || Unused
|-
| <code>bStatExplode</code> || Unused by vanilla — set 1 and every bullet explodes; balance accordingly
|-
| <code>bStatRangeRandom</code> / <code>bStatRangeTimer</code> || Bullet lifetime and its randomisation (how SHOTGUN pellets vanish unevenly)
|-
| <code>bStatSpType</code> || Appears to control TRIPLE's three-bullet spawn
|-
| <code>bStatSpTy1</code>–<code>3</code> || Undetermined; copy from the closest vanilla weapon
|-
| <code>bStatAimAngleAccl</code> / <code>Dccl</code> / <code>Limit</code> || Aim rotation speed/deceleration/max angle — only NOPPY aims (limit 25)
|}

[[Category:Modding]]

Modding - Revision history

172.17.0.1: Style: no em dashes; Shop keeps only shop-scoped pity info

172.17.0.1: Match image display sizes to the source document

172.17.0.1: Add the original guide's 57 screenshots (hosted as extension assets)

172.17.0.1: Adapted from VirtuaVirtue's Downwell Modding Documentation, with decompilation findings