Terraria world file parser and saver written in javascript
- supports maps from 1.3.5.3 to 1.4.4.4
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 | remixWorld | Remix world (seed) enabled only >1.4.4 |
bool | noTrapsWorld | No traps world (seed) enabled only >1.4.4 |
bool | zenithWorld | Zenith world (seed) enabled only >1.4.4 |
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 |
bool | afterPartyOfDoom | ? only >1.4.4 |
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 | setBG0 | forest background style |
uint8 | setBG1 | corruption background style |
uint8 | setBG2 | jungle background style |
uint8 | setBG3 | snow background style |
uint8 | setBG4 | hallow background style |
uint8 | setBG5 | crimson background style |
uint8 | setBG6 | desert background style |
uint8 | setBG7 | 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 | setBG8 | mushroom biome background style only 1.4 |
uint8 | setBG9 | underworld background style only 1.4 |
uint8 | setBG10 | Forest 2 background style only 1.4 |
uint8 | setBG11 | Forest 3 background style only 1.4 |
uint8 | setBG12 | 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 |
bool | unlockedSlimeBlueSpawn | ? only >1.4.4 |
bool | unlockedMerchantSpawn | ? only >1.4.4 |
bool | unlockedDemolitionistSpawn | ? only >1.4.4 |
bool | unlockedPartyGirlSpawn | ? only >1.4.4 |
bool | unlockedDyeTraderSpawn | ? only >1.4.4 |
bool | unlockedTruffleSpawn | ? only >1.4.4 |
bool | unlockedArmsDealerSpawn | ? only >1.4.4 |
bool | unlockedNurseSpawn | ? only >1.4.4 |
bool | unlockedPrincessSpawn | ? only >1.4.4 |
bool | combatBookVolumeTwoWasUsed | ? only >1.4.4 |
bool | peddlersSatchelWasUsed | ? only >1.4.4 |
bool | unlockedSlimeGreenSpawn | ? only >1.4.4 |
bool | unlockedSlimeOldSpawn | ? only >1.4.4 |
bool | unlockedSlimePurpleSpawn | ? only >1.4.4 |
bool | unlockedSlimeRainbowSpawn | ? only >1.4.4 |
bool | unlockedSlimeRedSpawn | ? only >1.4.4 |
bool | unlockedSlimeYellowSpawn | ? only >1.4.4 |
bool | unlockedSlimeCopperSpawn | ? only >1.4.4 |
bool | fastForwardTimeToDusk | ? only >1.4.4 |
byte | moondialCooldown | ? only >1.4.4 |
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, shimmer) |
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 |
bool | invisibleBlock | is invisible block |
bool | invisibleWall | is invisible wall |
bool | fullBrightBlock | is full bright block |
bool | fullBrightWall | is full bright wall |
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 |
bool | shimmered | is shimmered |
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 |