Scrapbook Partitions

Version History

Build Version	Change Date	Change Type	Description
676042	2025-06-21	stable	Current version

Overview

The scrapbookpartitions module provides a sophisticated data management system for tracking player discovery progress in Don't Starve Together's scrapbook. It handles data partitioning, character-specific inspection tracking, backend synchronization, and persistent storage using compact bit-field encoding.

Usage Example

-- Check if a prefab has been seen in game
if TheScrapbookPartitions:WasSeenInGame("wilson") then
    print("Wilson has been encountered")
end

-- Record that a character inspected a prefab
TheScrapbookPartitions:SetInspectedByCharacter("deerclops", "wilson")

-- Check scrapbook viewing status
if TheScrapbookPartitions:WasViewedInScrapbook("beefalo") then
    print("Beefalo entry was viewed in scrapbook")
end

-- Get discovery level (0=unknown, 1=seen, 2=inspected)
local level = TheScrapbookPartitions:GetLevelFor("chester")
print("Chester discovery level:", level)

Architecture

Data Storage Structure

The system uses a 32-bit integer to store scrapbook data for each prefab:

Bits 1-8: Flags (viewed in scrapbook, etc.)
Bits 9-32: Character inspection mask (24 character slots)

Partitioning System

Data is distributed across 16 buckets (0-15) using hash-based partitioning to optimize backend storage and reduce load.

Constants

FLAGS

Status: stable

Description: Bit flags for tracking scrapbook states.

Flag	Value	Description
`VIEWED_IN_SCRAPBOOK`	`0x00000001`	Entry was viewed in scrapbook UI

LOOKUP_LIST

Status: stable

Description: Character bit masks for tracking per-character inspections.

Character	Bit Mask	Slot
`wilson`	`0x00000100`	1
`willow`	`0x00000200`	2
`wolfgang`	`0x00000400`	3
`wendy`	`0x00000800`	4
`wx78`	`0x00001000`	5
`wickerbottom`	`0x00002000`	6
`woodie`	`0x00004000`	7
`wes`	`0x00008000`	8
`waxwell`	`0x00010000`	9
`wathgrithr`	`0x00020000`	10
`webber`	`0x00040000`	11
`winona`	`0x00080000`	12
`warly`	`0x00100000`	13
`wortox`	`0x00200000`	14
`wormwood`	`0x00400000`	15
`wurt`	`0x00800000`	16
`walter`	`0x01000000`	17
`wanda`	`0x02000000`	18

BUCKETS_MASK

Value: 0xF (16 buckets)

Status: stable

Description: Mask for distributing data across storage buckets.

Class: ScrapbookPartitions

Constructor

local ScrapbookPartitions = Class(function(self)
    self.storage = {}
    self.dirty_buckets = {}
end)

Core Methods

scrapbook:RedirectThing(thing)

Status: stable

Description: Converts entity instances or other objects to their string representation for scrapbook tracking.

Parameters:

thing (EntityScript|string): Entity instance or prefab name

Returns:

(string): Prefab name for scrapbook tracking

Example:

-- With entity instance
local prefab_name = TheScrapbookPartitions:RedirectThing(inst)

-- With string
local prefab_name = TheScrapbookPartitions:RedirectThing("wilson")

scrapbook:WasSeenInGame(thing)

Status: stable

Description: Checks if a prefab has been encountered in the game world.

Parameters:

thing (string|EntityScript): Prefab name or entity to check

Returns:

(boolean): True if the prefab has been seen

Example:

if TheScrapbookPartitions:WasSeenInGame("deerclops") then
    print("Deerclops has been encountered")
end

scrapbook:SetSeenInGame(thing)

Status: stable

Description: Marks a prefab as having been encountered in the game world.

Parameters:

thing (string|EntityScript): Prefab name or entity to mark as seen

Example:

-- When player encounters a new creature
TheScrapbookPartitions:SetSeenInGame("beefalo")

scrapbook:WasViewedInScrapbook(thing)

Status: stable

Description: Checks if a prefab entry was viewed in the scrapbook UI.

Parameters:

thing (string|EntityScript): Prefab name or entity to check

Returns:

(boolean): True if viewed in scrapbook

Example:

if not TheScrapbookPartitions:WasViewedInScrapbook("chester") then
    -- Show "new" indicator in scrapbook
    ShowNewEntryIndicator("chester")
end

scrapbook:SetViewedInScrapbook(thing, value)

Status: stable

Description: Marks a prefab entry as viewed or unviewed in the scrapbook UI.

Parameters:

thing (string|EntityScript): Prefab name or entity
value (boolean): True to mark as viewed, false to mark as unviewed (optional, defaults to true)

Example:

-- Mark as viewed when player opens scrapbook entry
TheScrapbookPartitions:SetViewedInScrapbook("spider", true)

-- Mark as new when content is updated
TheScrapbookPartitions:SetViewedInScrapbook("spider", false)

scrapbook:WasInspectedByCharacter(thing, character)

Status: stable

Description: Checks if a specific character has personally inspected a prefab.

Parameters:

thing (string|EntityScript): Prefab name or entity to check
character (string): Character prefab name

Returns:

(boolean): True if the character has inspected this prefab

Example:

if TheScrapbookPartitions:WasInspectedByCharacter("tentacle", "wilson") then
    print("Wilson has inspected a tentacle")
end

scrapbook:SetInspectedByCharacter(thing, character)

Status: stable

Description: Records that a specific character has inspected a prefab.

Parameters:

thing (string|EntityScript): Prefab name or entity
character (string): Character prefab name

Example:

-- When player inspects something
local function OnInspect(inst, prefab)
    TheScrapbookPartitions:SetInspectedByCharacter(prefab, inst.prefab)
end

scrapbook:GetLevelFor(thing)

Status: stable

Description: Returns the discovery level for a prefab.

Parameters:

thing (string|EntityScript): Prefab name or entity to check

Returns:

(number): Discovery level
- 0: Unknown/never seen
- 1: Seen but not inspected
- 2: Seen and inspected

Example:

local level = TheScrapbookPartitions:GetLevelFor("koalefant_summer")
if level == 0 then
    print("Never encountered")
elseif level == 1 then
    print("Seen but not inspected")
elseif level == 2 then
    print("Fully discovered")
end

Teaching/Learning Methods

scrapbook:TryToTeachScrapbookData_Random(numofentries)

Status: stable

Description: Randomly teaches a specified number of unknown scrapbook entries.

Parameters:

numofentries (number): Number of entries to teach

Returns:

(boolean): True if any entries were taught

Example:

-- Give player some random scrapbook knowledge
local learned = TheScrapbookPartitions:TryToTeachScrapbookData_Random(3)
if learned then
    print("Learned new scrapbook entries!")
end

scrapbook:TryToTeachScrapbookData_Special(index)

Status: stable

Description: Teaches scrapbook entries from a special page collection.

Parameters:

index (number): Special page index to teach from

Returns:

(boolean): True if any entries were taught

scrapbook:TryToTeachScrapbookData_Note(entry)

Status: stable

Description: Teaches a specific scrapbook entry and opens it in the UI.

Parameters:

entry (string): Prefab name to teach and display

Returns:

(boolean): Always returns true

Example:

-- When player finds a scrapbook note
TheScrapbookPartitions:TryToTeachScrapbookData_Note("ancient_statue")

scrapbook:TryToTeachScrapbookData(is_server, inst)

Status: stable

Description: Main teaching function that determines what type of scrapbook data to teach based on the item.

Parameters:

is_server (boolean): Whether this is running on the server
inst (EntityScript): The scrapbook item entity

Returns:

(boolean): True if any entries were taught

Storage and Synchronization

scrapbook:Save(force_save)

Status: stable

Description: Saves scrapbook data to local persistent storage.

Parameters:

force_save (boolean): Whether to force saving all buckets (optional)

scrapbook:Load()

Status: stable

Description: Loads scrapbook data from local persistent storage.

scrapbook:ApplyOnlineProfileData()

Status: stable

Description: Merges online profile data with local scrapbook data.

Returns:

(boolean): True if synchronization was successful

scrapbook:UpdateStorageData(hashed, newdata)

Status: stable

Description: Updates a single storage entry and marks it for synchronization.

Parameters:

hashed (number): Hash of the prefab name
newdata (number): New bit-field data value

Debug Methods

scrapbook:DebugDeleteAllData()

Status: stable

Description: Debug function to delete all scrapbook data.

Example:

-- WARNING: This erases all scrapbook progress
TheScrapbookPartitions:DebugDeleteAllData()

scrapbook:DebugSeenEverything()

Status: stable

Description: Debug function to mark all prefabs as seen.

scrapbook:DebugUnlockEverything()

Status: stable

Description: Debug function to fully unlock all scrapbook entries.

Global Instance

TheScrapbookPartitions

Type: ScrapbookPartitions

Status: stable

Description: Global instance of the scrapbook partitions system.

Common Usage Patterns

Player Discovery Tracking

-- When player encounters a new entity
local function OnEntitySeen(inst, viewer)
    if inst.prefab and viewer == ThePlayer then
        TheScrapbookPartitions:SetSeenInGame(inst.prefab)
    end
end

-- When player inspects something
local function OnEntityInspected(inst, viewer)
    if inst.prefab and viewer == ThePlayer then
        TheScrapbookPartitions:SetInspectedByCharacter(inst.prefab, viewer.prefab)
    end
end

Scrapbook UI Integration

-- Check if entry should show "new" indicator
local function ShouldShowNewIndicator(prefab)
    return TheScrapbookPartitions:WasSeenInGame(prefab) and
           not TheScrapbookPartitions:WasViewedInScrapbook(prefab)
end

-- When player views an entry in scrapbook
local function OnScrapbookEntryViewed(prefab)
    TheScrapbookPartitions:SetViewedInScrapbook(prefab, true)
end

Progress Calculation

-- Calculate completion statistics
local function GetScrapbookStats()
    local total = 0
    local seen = 0
    local inspected = 0
    
    local scrapbook_prefabs = require("scrapbook_prefabs")
    for prefab, included in pairs(scrapbook_prefabs) do
        if included then
            total = total + 1
            local level = TheScrapbookPartitions:GetLevelFor(prefab)
            if level >= 1 then
                seen = seen + 1
            end
            if level >= 2 then
                inspected = inspected + 1
            end
        end
    end
    
    return {
        total = total,
        seen = seen,
        inspected = inspected,
        seen_percent = math.floor((seen / total) * 100),
        inspected_percent = math.floor((inspected / total) * 100)
    }
end

Modded Character Support

-- Modded characters fall back to Wilson for tracking
local function GetEffectiveCharacterForScrapbook(character)
    if table.contains(MODCHARACTERLIST, character) then
        return "wilson"
    end
    return character
end

Technical Details

Bit Field Structure

-- 32-bit storage layout:
-- 0x???????? = [CHARACTER_MASK:24][FLAGS:8]
-- 
-- Example for Wilson inspecting a spider:
-- 0x00000101 = Wilson bit (0x100) + Viewed flag (0x001)

Hash Distribution

-- Prefabs are distributed across 16 buckets
local bucket = hash("spider") & 0xF  -- Bucket 0-15

Storage Keys

-- Local storage: "scrapbook_0" through "scrapbook_15"
-- Backend storage: "SCRAPBOOK0" through "SCRAPBOOK15"

Integration Notes

Character inspection data is merged when switching between characters
Modded characters use Wilson as a fallback for data storage
Backend synchronization occurs with configurable delays
Local storage provides offline functionality

Scrapbook Prefabs: Registry of trackable prefabs
Class: Base class system
Constants: Character list and configuration values

Version History​

Overview​

Usage Example​

Architecture​

Data Storage Structure​

Partitioning System​

Constants​

FLAGS​

LOOKUP_LIST​

BUCKETS_MASK​

Class: ScrapbookPartitions​

Constructor​

Core Methods​

scrapbook:RedirectThing(thing)​

scrapbook:WasSeenInGame(thing)​

scrapbook:SetSeenInGame(thing)​

scrapbook:WasViewedInScrapbook(thing)​

scrapbook:SetViewedInScrapbook(thing, value)​

scrapbook:WasInspectedByCharacter(thing, character)​

scrapbook:SetInspectedByCharacter(thing, character)​

scrapbook:GetLevelFor(thing)​

Teaching/Learning Methods​

scrapbook:TryToTeachScrapbookData_Random(numofentries)​

scrapbook:TryToTeachScrapbookData_Special(index)​

scrapbook:TryToTeachScrapbookData_Note(entry)​

scrapbook:TryToTeachScrapbookData(is_server, inst)​

Storage and Synchronization​

scrapbook:Save(force_save)​

scrapbook:Load()​

scrapbook:ApplyOnlineProfileData()​

scrapbook:UpdateStorageData(hashed, newdata)​

Debug Methods​

scrapbook:DebugDeleteAllData()​

scrapbook:DebugSeenEverything()​

scrapbook:DebugUnlockEverything()​

Global Instance​

TheScrapbookPartitions​

Common Usage Patterns​

Player Discovery Tracking​

Scrapbook UI Integration​

Progress Calculation​

Modded Character Support​

Technical Details​

Bit Field Structure​

Hash Distribution​

Storage Keys​

Integration Notes​

Related Modules​

Version History

Overview

Usage Example

Architecture

Data Storage Structure

Partitioning System

Constants

FLAGS

LOOKUP_LIST

BUCKETS_MASK

Class: ScrapbookPartitions

Constructor

Core Methods

scrapbook:RedirectThing(thing)

scrapbook:WasSeenInGame(thing)

scrapbook:SetSeenInGame(thing)

scrapbook:WasViewedInScrapbook(thing)

scrapbook:SetViewedInScrapbook(thing, value)

scrapbook:WasInspectedByCharacter(thing, character)

scrapbook:SetInspectedByCharacter(thing, character)

scrapbook:GetLevelFor(thing)

Teaching/Learning Methods

scrapbook:TryToTeachScrapbookData_Random(numofentries)

scrapbook:TryToTeachScrapbookData_Special(index)

scrapbook:TryToTeachScrapbookData_Note(entry)

scrapbook:TryToTeachScrapbookData(is_server, inst)

Storage and Synchronization

scrapbook:Save(force_save)

scrapbook:Load()

scrapbook:ApplyOnlineProfileData()

scrapbook:UpdateStorageData(hashed, newdata)

Debug Methods

scrapbook:DebugDeleteAllData()

scrapbook:DebugSeenEverything()

scrapbook:DebugUnlockEverything()

Global Instance

TheScrapbookPartitions

Common Usage Patterns

Player Discovery Tracking

Scrapbook UI Integration

Progress Calculation

Modded Character Support

Technical Details

Bit Field Structure

Hash Distribution

Storage Keys

Integration Notes

Related Modules