Terraria world file - js

Terraria world file parser and saver written in javascript

- supports maps from 1.3.5.3 to 1.4.3

Feel free to contribute 🌳

Usage

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
});

Documentation:

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 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