Room instances (#363)

Volte6 · web-flow · commit 12930d40e92e · 2025-05-02T20:33:22.000-07:00
# Description

The goal of this PR is to split Room data files into two save forms:

1. The "Template", saved in `_datafiles/world/{worldname}/rooms/` which is just the normal, empty state room definition. This is how the room should be loaded into the memory the first time it is ever encountered. Items shouldn't be on the floor (unless it is desired to start with an item on the floor), gold, containers, etc. are all in their initial state.
2. The "Instance", saved in `_datafiles/world/{worldname}/rooms.instances/` which is everything (or most things) that have changed about the room and are worth saving in case the room gets unloaded from memory.

## Changes

- Updated room "Template" data files to remove random objects that were saved and committed into rooms in the past.
- Instance loading/saving and Template loading/saving are distinct operations with different purposes, and code functions etc. have been created to handle them.
  - Developers should generally not have to interface with these, they are for precise modification to specific data when needed, such as in admin commands. The `rooms.LoadRoom()` function remains the primary way to load room data.
- Fixed some inefficiencies with room filenames, should have been caching but wasn't.
- Added a makefile target to delete all instance data for purposes of testing.
- Added an event and handler to rebuild mapper data.
- Fixed a lot of messy/poorly named functions and variables to try and make clearer
- Added lots of code comments for whatever poor soul must revisit this process.
- Moved room save/load functions to own file in package folder.
- Updated admin `build` command to modify template data.
- Updated admin `room` command to modify template data.
diff --git a/.gitignore b/.gitignore
@@ -4,6 +4,7 @@ _datafiles/**/users/*
 _datafiles/**/plugin-data/*
 **/config-overrides.yaml
 **/.roundcount
+**/rooms.instances
 vendor/
 server.crt
 server.key
diff --git a/Makefile b/Makefile
@@ -63,6 +63,11 @@ clean:
 	$(DOCKER_COMPOSE) down --volumes --remove-orphans
 	docker system prune -a
 
+.PHONY: clean-instances
+clean-instances: ### Deletes all room instance data. Starts the world fresh.
+	rm -Rf _datafiles/world/default/rooms.instances
+	rm -Rf _datafiles/world/empty/rooms.instances
+
 ## Run Targets
 
 .PHONY: run 
diff --git a/_datafiles/world/default/rooms/catacombs/89.yaml b/_datafiles/world/default/rooms/catacombs/89.yaml
@@ -14,9 +14,6 @@ exits:
     roomid: 81
   north:
     roomid: 88
-items:
-- itemid: 10002
-gold: 6
 spawninfo:
 - mobid: 15
   message: The bones in the room stir, and a skeleton rises from the dirt.
diff --git a/_datafiles/world/default/rooms/dark_forest/878.yaml b/_datafiles/world/default/rooms/dark_forest/878.yaml
@@ -18,9 +18,6 @@ containers:
   ornate chest:
     lock:
       difficulty: 8
-    items:
-    - itemid: 25
-    gold: 1
 exits:
   out:
     roomid: 877
diff --git a/_datafiles/world/default/rooms/endless_trashheap/142.yaml b/_datafiles/world/default/rooms/endless_trashheap/142.yaml
@@ -16,13 +16,6 @@ exits:
     roomid: 143
   west:
     roomid: 141
-items:
-- itemid: 20001
-- itemid: 20001
-- itemid: 20001
-- itemid: 20011
-- itemid: 20011
-- itemid: 20011
 idlemessages:
 - the mountain of trash shifts slightly.
 - the trash heal trembles, threatening to collapse at any moment.
diff --git a/_datafiles/world/default/rooms/endless_trashheap/152.yaml b/_datafiles/world/default/rooms/endless_trashheap/152.yaml
@@ -16,8 +16,6 @@ exits:
     roomid: 153
   south:
     roomid: 151
-items:
-- itemid: 5
 idlemessages:
 - the mountain of trash shifts slightly.
 - the trash heal trembles, threatening to collapse at any moment.
diff --git a/_datafiles/world/default/rooms/frost_lake/828.yaml b/_datafiles/world/default/rooms/frost_lake/828.yaml
@@ -13,8 +13,6 @@ maplegend: Rocks
 exits:
   southeast:
     roomid: 319
-items:
-- itemid: 10016
 idlemessages:
 - A gust of wind sends a chill throgh the air.
 - A large wave crashes against the shore.
diff --git a/_datafiles/world/default/rooms/frostfang/21.yaml b/_datafiles/world/default/rooms/frostfang/21.yaml
@@ -18,8 +18,6 @@ exits:
     roomid: 22
   west:
     roomid: 20
-stash:
-- itemid: 10001
 spawninfo:
 - mobid: 1
   message: A rat scurries out from a dark hole and wiggles its whiskers.
diff --git a/_datafiles/world/default/rooms/frostfang/269.yaml b/_datafiles/world/default/rooms/frostfang/269.yaml
@@ -13,8 +13,6 @@ biome: house
 exits:
   south:
     roomid: 259
-items:
-- itemid: 26
 spawninfo:
 - mobid: 26
   levelmod: 10
diff --git a/_datafiles/world/default/rooms/frostfang/433.yaml b/_datafiles/world/default/rooms/frostfang/433.yaml
@@ -15,8 +15,6 @@ exits:
     roomid: 111
   west:
     roomid: 166
-items:
-- itemid: 5
 spawninfo:
 - itemid: 5
   respawnrate: 1 real day
diff --git a/_datafiles/world/default/rooms/frostfang/6.yaml b/_datafiles/world/default/rooms/frostfang/6.yaml
@@ -13,7 +13,6 @@ exits:
     roomid: 36
   south:
     roomid: 5
-gold: 124
 spawninfo:
 - mobid: 2
   message: A town guard emerges from a nearby building.
diff --git a/_datafiles/world/default/rooms/frostfang/784.yaml b/_datafiles/world/default/rooms/frostfang/784.yaml
@@ -14,10 +14,6 @@ containers:
   chest:
     lock:
       difficulty: 3
-    items:
-    - itemid: 30002
-      uses: 1
-    gold: 75
 exits:
   south:
     roomid: 778
diff --git a/_datafiles/world/default/rooms/frostfang_slums/436.yaml b/_datafiles/world/default/rooms/frostfang_slums/436.yaml
@@ -15,8 +15,6 @@ exits:
     roomid: 435
   west:
     roomid: 437
-items:
-- itemid: 20011
 spawninfo:
 - mobid: 12
   message: A massive rat saunters out from the shadows.
diff --git a/_datafiles/world/default/rooms/frostfang_slums/462.yaml b/_datafiles/world/default/rooms/frostfang_slums/462.yaml
@@ -19,8 +19,6 @@ exits:
     roomid: 464
   west:
     roomid: 447
-items:
-- itemid: 20011
 spawninfo:
 - mobid: 12
   message: A massive rat saunters out from the shadows.
diff --git a/_datafiles/world/default/rooms/frostfang_slums/474.yaml b/_datafiles/world/default/rooms/frostfang_slums/474.yaml
@@ -15,8 +15,6 @@ exits:
     roomid: 473
   west:
     roomid: 475
-items:
-- itemid: 20010
 gold: 10
 spawninfo:
 - mobid: 28
diff --git a/internal/events/eventtypes.go b/internal/events/eventtypes.go
@@ -348,6 +348,18 @@ type Party struct {
 
 func (p Party) Type() string { return `Party` }
 
+// Rebuilds mapper for a given RoomId
+// NOTE: RoomId should USUALLY be the Room's Zone.RootRoomId
+type RebuildMap struct {
+	MapRootRoomId int
+	SkipIfExists  bool
+}
+
+func (r RebuildMap) Type() string { return `RebuildMap` }
+func (r RebuildMap) UniqueID() string {
+	return `RebuildMap-` + strconv.Itoa(r.MapRootRoomId) + `-` + strconv.FormatBool(r.SkipIfExists)
+}
+
 type RedrawPrompt struct {
 	UserId        int
 	OnlyIfChanged bool
diff --git a/internal/hooks/RebuildMap_HandleMapRebuild.go b/internal/hooks/RebuildMap_HandleMapRebuild.go
@@ -0,0 +1,16 @@
+package hooks
+
+import (
+	"github.com/GoMudEngine/GoMud/internal/events"
+	"github.com/GoMudEngine/GoMud/internal/mapper"
+)
+
+// Handles force rebuilding maps via event
+func HandleMapRebuild(e events.Event) events.ListenerReturn {
+
+	evt := e.(events.RebuildMap)
+
+	mapper.GetMapper(evt.MapRootRoomId, !evt.SkipIfExists)
+
+	return events.Continue
+}
diff --git a/internal/hooks/hooks.go b/internal/hooks/hooks.go
@@ -75,6 +75,8 @@ func RegisterListeners() {
 
 	events.RegisterListener(events.Broadcast{}, Broadcast_SendToAll)
 
+	events.RegisterListener(events.RebuildMap{}, HandleMapRebuild)
+
 	// Log tee to users
 	events.RegisterListener(events.Log{}, FollowLogs)
 
diff --git a/internal/mapper/mapper.go b/internal/mapper/mapper.go
@@ -200,6 +200,10 @@ type crawlRoom struct {
 	Pos    positionDelta // Its x/y/z position relative to the root node
 }
 
+func (r *mapper) RootRoomId() int {
+	return r.rootRoomId
+}
+
 func (r *mapper) CrawledRoomIds() []int {
 	roomIds := []int{}
 	for roomId := range r.crawledRooms {
@@ -232,6 +236,9 @@ func (r *mapper) Start() {
 		}
 
 		node := r.getMapNode(roomNow.RoomId)
+		if node == nil {
+			continue
+		}
 		node.Pos = roomNow.Pos
 
 		// Add to crawled list so we don't revisit it
@@ -461,6 +468,9 @@ func (r *mapper) GetLimitedMap(centerRoomId int, c Config) mapRender {
 		dstPos = roomNow.Pos
 
 		node := r.getMapNode(roomNow.RoomId)
+		if node == nil {
+			continue
+		}
 
 		symbol = node.Symbol
 		legend = node.Legend
@@ -815,23 +825,56 @@ func (r *mapper) getMapNode(roomId int) *mapNode {
 	return mNode
 }
 
+// Returns the mapper if it exists, otherwise does nothing.
+func GetMapperIfExists(roomId int) *mapper {
+	if zoneName, ok := roomIdToMapperCache[roomId]; ok {
+		return mapperZoneCache[zoneName]
+	}
+	return nil
+}
+
+// Get the mapper if it exists, otherwises generates a new map from the roomId
 func GetMapper(roomId int, forceRefresh ...bool) *mapper {
 
+	var cachedMap *mapper = nil
 	// Check the room-to-cache lookup
+
 	if zoneName, ok := roomIdToMapperCache[roomId]; ok {
-		return mapperZoneCache[zoneName]
+		cachedMap = mapperZoneCache[zoneName]
+		if len(forceRefresh) == 0 || !forceRefresh[0] {
+			return cachedMap
+		}
+	}
+
+	// We are force rebuilding (or building if not exists) at this point
+
+	// Since we will be regenerating the whole map,
+	// lets clear out any roomId's tracked for this room.
+	// That way if something has changed, such as a room moving to a different map,
+	// It won't point to here.
+	if cachedMap != nil {
+		for crawledRoomId, _ := range cachedMap.crawledRooms {
+			delete(roomIdToMapperCache, crawledRoomId)
+		}
 	}
 
-	zoneName := ``
-	if room := rooms.LoadRoom(roomId); room != nil {
-		zoneName = room.Zone
-		zoneName += `-` + strconv.Itoa(roomId)
+	room := rooms.LoadRoom(roomId)
+	if room == nil {
+		return nil
 	}
 
-	// not found. Will need to create one.
+	// Track the time it takes
 	tStart := time.Now()
 
+	// multiple maps MIGHT exist within a zone, so use the zone+maps root to track it uniquely.
+	// We could just use the roomId, but this makes debugging easier.
+	zoneName := room.Zone + `-` + strconv.Itoa(roomId)
+
 	m := NewMapper(roomId)
+	if m == nil {
+		mudlog.Error("GetMapper", "error", "Could not generate a mapper for RoomId", "RoomId", roomId)
+		return nil
+	}
 	m.Start()
 
 	mudlog.Info("New Mapper", "zone", zoneName, "time taken", time.Since(tStart))
diff --git a/internal/mutators/mutators.go b/internal/mutators/mutators.go
@@ -38,9 +38,37 @@ func (tb TextBehavior) IsValid() bool {
 type MutatorList []Mutator
 
 type Mutator struct {
-	MutatorId      string // Short text that will uniquely identify this modifier ("dusty")
-	SpawnedRound   uint64 `yaml:"-"` // Tracks when this mutator was created (useful for decay)
-	DespawnedRound uint64 `yaml:"-"` // Track when it decayed to nothing.
+	MutatorId      string `yaml:"mutatorid,omitempty"`      // Short text that will uniquely identify this modifier ("dusty")
+	SpawnedRound   uint64 `yaml:"spawnedround,omitempty"`   // Tracks when this mutator was created (useful for decay)
+	DespawnedRound uint64 `yaml:"despawnedround,omitempty"` // Track when it decayed to nothing.
+}
+
+// This is a special function used for when room instance data is saved
+// It handles checking for special equality cases that the normal reflect.DeepEqual() doesn't handle the way we want.
+func (m MutatorList) SkipInstanceSave(other any) bool {
+	return false
+	m2, ok := other.(MutatorList)
+	if !ok {
+		return false
+	}
+
+	if len(m) != len(m2) { // length different?
+		return false
+	}
+
+	for i, _ := range m {
+
+		if m[i].MutatorId != m2[i].MutatorId {
+			return false
+		}
+
+		if m[i].Removable() != m2[i].Removable() {
+			return false
+		}
+
+	}
+
+	return true
 }
 
 type TextModifier struct {
diff --git a/internal/plugins/plugins.go b/internal/plugins/plugins.go
@@ -68,6 +68,10 @@ type Plugin struct {
 
 func New(name string, version string) *Plugin {
 
+	// name can only contain alphanumeric or underscores.
+	reg, _ := regexp.Compile("[^a-zA-Z0-9_]+")
+	name = reg.ReplaceAllString(name, "_")
+
 	if !registrationOpen {
 		return nil
 	}
@@ -83,6 +87,15 @@ func New(name string, version string) *Plugin {
 		Web:       newWebConfig(),
 	}
 
+	// Prepopulate the script commands with a single `version()` function.
+	// The primary purpose of this is to force the module name to be
+	// registered in the modules namespace of scripts.
+	// For example, if the module is named "fishing", this will ensure
+	// `modules.fishing` is populated, because we've defined `modules.fishing.version()`
+	p.Callbacks.scriptCommands[p.name] = map[string]any{
+		`version`: func() string { return version },
+	}
+
 	registry = append(registry, p)
 	return p
 }
@@ -214,6 +227,9 @@ func (p pluginRegistry) Stat(name string) (fs.FileInfo, error) {
 }
 
 func (p *Plugin) Requires(modname string, modversion string) {
+	// modname can only contain alphanumeric or underscores.
+	reg, _ := regexp.Compile("[^a-zA-Z0-9_]+")
+	modname = reg.ReplaceAllString(modname, "_")
 	p.dependencies = append(p.dependencies, dependency{modname, modversion})
 }
 
diff --git a/internal/rooms/roommanager.go b/internal/rooms/roommanager.go
diff --git a/internal/rooms/rooms.go b/internal/rooms/rooms.go
diff --git a/internal/rooms/save_and_load.go b/internal/rooms/save_and_load.go
diff --git a/internal/usercommands/admin.build.go b/internal/usercommands/admin.build.go
diff --git a/internal/usercommands/admin.room.go b/internal/usercommands/admin.room.go
diff --git a/main.go b/main.go
