Terraria world file - typescript

Terraria world file parser written in typescript

- supports maps from 1.3.5.3 to 1.4.4.9

Feel free to contribute 🌳

Installation

https://www.npmjs.com/package/terraria-world-file

npm install terraria-world-file

pnpm add terraria-world-file

yarn add terraria-world-file

bun add terraria-world-file

Usage

import { fileLoader } from 'terraria-world-file/node'
import TerrariaWorldParser from 'terraria-world-file'

const world = await new TerrariaWorldParser()
  .loadFile(fileLoader, '/map.wld')
  .parse()

console.log('World seed is ' + world.header.seedText)

// todo: Add support for saving
//
// world.header.name = 'Edited ' + world.header.name
// new terrariaWorldSaver().save(world)

Documentation:

Up to date Typedocs

Outdated manually typed

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

Return object:

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 modeonly >1.4.0.1 bool | drunkWorld | drunk world (seed) enabledonly >1.4.0.1 bool | getGoodWorld | good world (seed) enabledonly >1.4.0.3 bool | getTenthAnniversaryWorld | Tenth Anniversary world (seed) enabledonly >1.4.2.3 bool | dontStarveWorld | Dont Starve world (seed) enabledonly >1.4.3 bool | notTheBeesWorld | Not the bees world (seed) enabledonly >1.4.3 bool | remixWorld | Remix world (seed) enabledonly >1.4.4 bool | noTrapsWorld | No traps world (seed) enabledonly >1.4.4 bool | zenithWorld | Zenith world (seed) enabledonly >1.4.4 bool | expertMode | expert modeonly 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 styleonly 1.4 uint8 | setBG9 | underworld background styleonly 1.4 uint8 | setBG10 | Forest 2 background styleonly 1.4 uint8 | setBG11 | Forest 3 background styleonly 1.4 uint8 | setBG12 | Forest 4 background styleonly 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 idonly 1.4 int32 | savedOreTierIron | tier 2 normalmode block idonly 1.4 int32 | savedOreTierSilver | tier 3 normalmode block idonly 1.4 int32 | savedOreTierGold | tier 4 normalmode block idonly 1.4 bool | boughtCat | bought catonly 1.4 bool | boughtDog | bought dogonly 1.4 bool | boughtBunny | bought bunnyonly 1.4 bool | downedEmpressOfLight | killed empress of lightonly 1.4 bool | downedQueenSlime | killed queen slimeonly 1.4 bool | downedDeerclops | killed deerclopsonly 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 | nameonly townNPCs bool | homeless | is homelessonly 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 pylontype is determined by its position in the worldonly 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