Terraria world file parser and saver written in javascript
- supports maps from 1.3.5.3 to 1.4.3
Feel free to contribute 🌳
import terrariaWorldParser from "/terraria-world-parser.js";
import terrariaWorldSaver from "/terraria-world-saver.js";
let world = await new terrariaWorldParser().loadFile(mapFile || "/map.wld");
world = world.parse();
const name = world.header.name;
const newName = "Canvas";
console.log( "Old name: " + name );
console.log( "New name: " + newName );
world.header.name = newName;
let newWorldFile = new terrariaWorldSaver().save({
world
});constructor new terrariaWorldParser()
node method loadBuffer(buffer buffer)
node method loadFileSync(string path)
node method async loadFile(string path)
browser method async loadFile(File file)
— Loads file buffer
— Returns instance
method parse([object options])
string array options.sections
— Sections to parse
— Default: ["fileFormatHeader", "header", "tiles", "chests", "signs", "NPCs", "tileEntities",
"weightedPressurePlates", "rooms", "bestiary", "creativePowers", "footer"]
boolean options.ignorePointers
— Disables checking whether buffer offset matches the next section pointer
— Use if some sections are corrupted
— Default: false
boolean options.ignoreBounds
— Fills the data with zeros if the buffer is outside bounds
— Use if some sections are missing
— Default: false
function options.progressCallback(int percent)
— Called when loading progress changes
— Parses file
— Returns buffer
constructor new terrariaWorldSaver()
browser method save(object options)
object options.world
— Same object structure as parser return object
— Required
function [options.progressCallback(int percent)]
— Called when loading progress changes
— Saves object
— Returns buffer
TODO: node method save(object options)
— If you are reading this and want to help, you can create a pull request :)
Error TerrariaWorldParserError
| or
Error TerrariaWorldSaverError
string name = "TerrariaWorldParserError"
| or
string name = "TerrariaWorldSaverError"
string message = onlyFriendlyMessage + ":\n" + onlyName + ": " + onlyMessage
string onlyFriendlyMessage
— user friendly error message
string onlyName
— original thrown error name
string onlyMessage
— original thrown error message
object fileFormatHeader
| Type | Variable | Description |
|---|---|---|
| int32 | version | map file version |
| 7 bytes string | magicNumber | file format magic number |
| uint8 | fileType | terraria's file type |
| uint32 | revision | map was saved count |
| uint64 | favorite | favorite |
| int32 array | pointers | offsets of sections |
| bool array | importants | tile frame importants (animated, big sprite, more variants...) index = block id |
object header
| Type | Variable | Description |
|---|---|---|
| string | mapName | map name |
| string | seedText | map seed |
| uint64 | worldGeneratorVersion | version of the world generator, returns 8 bytes array |
| uint8 array | guid | guid of the map |
| string | guidString | guid of the map (only browser parser) |
| int32 | worldId | map ID |
| int32 | leftWorld | map dimesion in pixels |
| int32 | rightWorld | ^ |
| int32 | topWorld | ^ |
| int32 | bottomWorld | ^ |
| int32 | maxTilesY | map dimension y in tiles |
| int32 | maxTilesX | map dimension x in tiles |
| int32 | gameMode | map game mode only >1.4.0.1 |
| bool | drunkWorld | drunk world (seed) enabled only >1.4.0.1 |
| bool | getGoodWorld | good world (seed) enabled only >1.4.0.3 |
| bool | getTenthAnniversaryWorld | Tenth Anniversary world (seed) enabled only >1.4.2.3 |
| bool | dontStarveWorld | Dont Starve world (seed) enabled only >1.4.3 |
| bool | notTheBeesWorld | Not the bees world (seed) enabled only >1.4.3 |
| bool | expertMode | expert mode only 1.3.5.3 |
| int64 | creationTime | time of creation, returns 8 bytes array (Datetime.ToBinary) |
| uint8 | moonType | moon type |
| int32 array | treeX | x positions where corresponding treeStyle ends |
| int32 array | treeStyle | tree styles |
| int32 array | caveBackX | x positions where corresponding caveBackStyles ends |
| int32 array | caveBackStyle | cave background styles |
| int32 | iceBackStyle | ice underground/cavern background style |
| int32 | jungleBackStyle | jungle underground/cavern background style |
| int32 | hellBackStyle | underworld background style |
| int32 | spawnTileX | position x of the spawn point |
| int32 | spawnTileY | position y of the spawn point |
| double | worldSurface | y dimension where cavern starts |
| double | rockLayer | y dimension where underground starts |
| double | tempTime | current time |
| bool | tempDayTime | is day time |
| int32 | tempMoonPhase | moon phase |
| bool | tempBloodMoon | is blood moon happening |
| bool | tempEclipse | is eclipse happening |
| int32 | dungeonX | position x of the dungeon base |
| int32 | dungeonY | position y of the dungeon base |
| bool | crimson | has crimson |
| bool | downedBoss1 | eye of cthulu killed |
| bool | downedBoss2 | eater of worlds killed |
| bool | downedBoss3 | skeletron killed |
| bool | downedQueenBee | queen bee killed |
| bool | downedMechBoss1 | the destroyes killed |
| bool | downedMechBoss2 | the skeletron prime killed |
| bool | downedMechBoss3 | the twins killed |
| bool | downedMechBossAny | any mechanical boss killed |
| bool | downedPlantBoss | plantera killed |
| bool | downedGolemBoss | golem killed |
| bool | downedSlimeKing | slime king killed |
| bool | savedGoblin | goblin saved |
| bool | savedWizard | wizard saved |
| bool | savedMech | mechanic saved |
| bool | downedGoblins | goblins endured |
| bool | downedClown | clown killed |
| bool | downedFrost | frost legion endured |
| bool | downedPirates | pirates endured |
| bool | shadowOrbSmashed | shadow orb / crimson heart smashed |
| bool | spawnMeteor | can meteor spawn |
| uint8 | shadowOrbCount | shadow orbs / crimson hearts smashed count (x/3) |
| int32 | altarCount | altars smashed count |
| bool | hardMode | hardmode |
| int32 | invasionDelay | ? |
| int32 | invasionSize | ? |
| int32 | invasionType | type of an event |
| double | invasionX | ? |
| double | slimeRainTime | ? |
| uint8 | sundialCooldown | cooldown of the Enchanted Sundial |
| bool | tempRaining | is currently raining |
| int32 | tempRainTime | current rain time |
| float | tempMaxRain | ? |
| int32 | oreTier1 | tier 1 hardmode ore block id |
| int32 | oreTier2 | tier 2 hardmode ore block id |
| int32 | oreTier3 | tier 3 hardmode ore block id |
| uint8 | setBGTree | forest background style |
| uint8 | setBGCorruption | corruption background style |
| uint8 | setBGJungle | jungle background style |
| uint8 | setBGSnow | snow background style |
| uint8 | setBGHallow | hallow background style |
| uint8 | setBGCrimson | crimson background style |
| uint8 | setBGDesert | desert background style |
| uint8 | setBGOcean | ocean background style |
| int32 | cloudBGActive | ? |
| int16 | numClouds | clouds count (max 200) |
| float | windSpeed | wind speed |
| string array | anglerWhoFinishedToday | name of players that completed angler quest |
| bool | savedAngler | angler saved |
| int32 | anglerQuest | id of the current angler quest (probably) |
| bool | savedStylist | stylist saved |
| bool | savedTaxCollector | tax collector saved |
| int32 | invasionSizeStart | ? |
| int32 | tempCultistDelay | ? |
| int32 array | killCount | kill counter of the enemies (index == id) |
| bool | fastForwardTime | ? |
| bool | downedFishron | fishron killed |
| bool | downedMartians | martians killed |
| bool | downedAncientCultist | cultists killed |
| bool | downedMoonlord | moon lord killed |
| bool | downedHalloweenKing | pumpking killed |
| bool | downedHalloweenTree | everscream killed |
| bool | downedChristmasIceQueen | ice queen killed |
| bool | downedChristmasSantank | santa-nk1 killed |
| bool | downedChristmasTree | mourning wood killed |
| bool | downedTowerSolar | solar pillar killed |
| bool | downedTowerVortex | vortex pillar killed |
| bool | downedTowerNebula | nebula pillar killed |
| bool | downedTowerStardust | stardust pillar killed |
| bool | TowerActiveSolar | solar pillar spawned |
| bool | TowerActiveVortex | vortex pillar spawned |
| bool | TowerActiveNebula | nebula pillar spawned |
| bool | TowerActiveStardust | stardust pillar spawned |
| bool | LunarApocalypseIsUp | lunar event active |
| bool | tempPartyManual | party started by player |
| bool | tempPartyGenuine | party started by random |
| int32 | tempPartyCooldown | party event cooldown |
| int32 array | tempPartyCelebratingNpcs | NPCs currently celebrating |
| bool | Temp_Sandstorm_Happening | is sandstorm happening |
| int32 | Temp_Sandstorm_TimeLeft | time left to sandstorm end |
| float | Temp_Sandstorm_Severity | severity of the sandstorm |
| float | Temp_Sandstorm_IntendedSeverity | intented severity of the sandstorm |
| bool | savedBartender | tavernkeed saved |
| bool | DD2Event_DownedInvasionT1 | old one's army tier 1 killed |
| bool | DD2Event_DownedInvasionT2 | old one's army tier 2 killed |
| bool | DD2Event_DownedInvasionT3 | old one's army tier 3 killed |
| uint8 | setBGMushroom | mushroom biome background style only 1.4 |
| uint8 | setBGUnderworld | underworld background style only 1.4 |
| uint8 | setBGTree2 | Forest 2 background style only 1.4 |
| uint8 | setBGTree3 | Forest 3 background style only 1.4 |
| uint8 | setBGTree4 | Forest 4 background style only 1.4 |
| bool | combatBookWasUsed | ? only 1.4 |
| int32 array | treeTopsVariations | ? only 1.4 |
| bool | forceHalloweenForToday | ? only 1.4 |
| bool | forceXMasForToday | ? only 1.4 |
| int32 | savedOreTierCopper | tier 1 normalmode block id only 1.4 |
| int32 | savedOreTierIron | tier 2 normalmode block id only 1.4 |
| int32 | savedOreTierSilver | tier 3 normalmode block id only 1.4 |
| int32 | savedOreTierGold | tier 4 normalmode block id only 1.4 |
| bool | boughtCat | bought cat only 1.4 |
| bool | boughtDog | bought dog only 1.4 |
| bool | boughtBunny | bought bunny only 1.4 |
| bool | downedEmpressOfLight | killed empress of light only 1.4 |
| bool | downedQueenSlime | killed queen slime only 1.4 |
| bool | downedDeerclops | killed deerclops only 1.4.3 |
2D objects array tiles
| Type | Variable | Description |
|---|---|---|
| uint8 / uint16 | blockId | tile id |
| uint8 / uint16 | wallId | wall id |
| int16 | frameX | frame x (tile frame important) |
| int16 | frameY | frame y (^) |
| string | slope | edited block (half, TR, TL, BR, BL) |
| uint8 | blockColor | block paint |
| uint8 | wallColor | wall paint |
| string | liquidType | liquid type (water, lava, honey) |
| uint8 | liquidAmount | liquid amount |
| bool | actuator | contains actuator |
| bool | actuated | is actuated |
| bool | wireRed | contains red wire |
| bool | wireBlue | contains blue wire |
| bool | wireGreen | contains green wire |
| bool | wireYellow | contains yellow wire |
objects array chests
| Type | Variable | Description |
|---|---|---|
| string | name | name of the chest |
| object | position | |
| | int32 | x | position x of the chest |
| | int32 | y | position y of the chest |
| object array | items | |
| | int16 | stack | stack of the item |
| | int32 | id | id of the item |
| | uint8 | prefix | id of the prefix for the item (modifier) |
objects array signs
| Type | Variable | Description |
|---|---|---|
| string | text | text of the sign |
| object | position | |
| | int32 | x | position x of the sign |
| | int32 | y | position y of the sign |
objects array NPCs
| Type | Variable | Description |
|---|---|---|
| int32 | id | id |
| bool | townNPC | is townNPC |
| bool | pillar | is pillar |
| string | name | name only townNPCs |
| bool | homeless | is homeless only townNPCs |
| object | position | |
| | float | x | position x of an npc |
| | float | y | position y of an npc |
| object | homePosition | only townNPCs |
| | int32 | x | position x of npc's home |
| | int32 | y | position y of npc's home |
objects array tileEntities
| Type | Variable | Description |
|---|---|---|
| uint8 | type | tile entity type |
| int32 | id | tile entity ID |
| object | position | |
| | int16 | x | position x of the tile entity |
| | int16 | y | position y of the tile entity |
| object | targetDummy | |
| | int16 | npc | ? |
| object | itemFrame | |
| | int16 | itemId | ID of the framed item |
| | uint8 | prefix | prefix of the framed item (modifier) |
| | int16 | stack | stack of the framed item |
| object | logicSensor | |
| | uint8 | logicCheck | type of the logic check (probably) |
| | bool | on | is on |
| object | displayDoll | only 1.4 |
| | objects array | items | size = 8 |
| | | int16 | itemId | item ID |
| | | uint8 | prefix | item modifier |
| | | int16 | stack | items stack |
| | objects array | dyes | size = 8 |
| | | int16 | itemId | dye ID |
| | | uint8 | prefix | dye modifier |
| | | int16 | stack | dye stack |
| object | weaponRack | only 1.4 |
| | int16 | itemId | item ID |
| | uint8 | prefix | item modifier |
| | int16 | stack | item stack |
| object | hatRack | only 1.4 |
| | objects array | items | size = 2 |
| | | int16 | itemId | item ID |
| | | uint8 | prefix | item modifier |
| | | int16 | stack | items stack |
| | objects array | dyes | size = 2 |
| | | int16 | itemId | dye ID |
| | | uint8 | prefix | dye modifier |
| | | int16 | stack | dye stack |
| object | foodPlatter | only 1.4 |
| | int16 | itemId | item ID |
| | uint8 | prefix | item modifier |
| | int16 | stack | item stack |
| bool | teleportationPylon | is pylon type is determined by its position in the world only 1.4 |
objects array weightedPressurePlates
| Type | Variable | Description |
|---|---|---|
| object : | position | |
| | int32 | x | position x of the pressurePlate |
| | int32 | y | position y of the pressurePlate |
objects array rooms
| Type | Variable | Description |
|---|---|---|
| int32 | NPCId | |
| object : | position | |
| | int32 | x | position x of the room |
| | int32 | y | position y of the room |
object bestiary
— only 1.4
| Type | Variable | Description |
|---|---|---|
| object : | NPCKills | |
| | string | [key] | name of the NPC |
| | int32 | [value] | given NPC kill count |
| strings array | NPCSights | names of NPCs that player encountered |
| strings array | NPCChats | names of NPCs that player chatted with |
object creativePowers
— only 1.4
| Type | Variable | Description |
|---|---|---|
| bool | freezeTime | Freeze Time enabled |
| float32 | modifyTimeRate | Time Speed Slider value |
| bool | freezeRainPower | Rain Change freeze enabled |
| bool | freezeWindDirectionAndStrength | Wind Change freeze enabled |
| float32 | difficultySliderPower | Enemy Difficulty Slider value |
| bool | stopBiomeSpreadPower | Infection Spread freeze enabled |
object footer
| Type | Variable | Description |
|---|---|---|
| bool | signoff1 | always true |
| string | signoff2 | map name |
| int32 | signoff3 | map id |