Rename Instance to World (#304)

4 files changed, 90 insertions, 59 deletions

diff --git a/azalea-world/src/container.rs b/azalea-world/src/container.rs
index 97bc2a1f..af344dc0 100644
--- a/azalea-world/src/container.rs
+++ b/azalea-world/src/container.rs
@@ -1,5 +1,6 @@
 use std::{
     collections::HashMap,
+    fmt::{self, Display},
     sync::{Arc, Weak},
 };
 
@@ -12,14 +13,14 @@ use parking_lot::RwLock;
 use rustc_hash::FxHashMap;
 use tracing::{debug, error};
 
-use crate::{ChunkStorage, Instance};
+use crate::{ChunkStorage, World};
 
-/// A container of [`Instance`]s (aka worlds).
+/// A container of [`World`] instances.
 ///
-/// Instances are stored as a Weak pointer here, so if no clients are using an
-/// instance it will be forgotten.
+/// Worlds are stored as a `Weak` pointer here, so if no clients are using a
+/// world then it will be forgotten.
 #[derive(Default, Resource)]
-pub struct InstanceContainer {
+pub struct Worlds {
     // We just refer to the chunks here and don't include entities because there's not that many
     // cases where we'd want to get every entity in the world (just getting the entities in chunks
     // should work fine).
@@ -29,22 +30,21 @@ pub struct InstanceContainer {
 
     // If it looks like we're relying on the server giving us unique world names, that's because we
     // are. An evil server could give us two worlds with the same name and then we'd have no way of
-    // telling them apart. We hope most servers are nice and don't do that though. It's only an
-    // issue when there's multiple clients with the same WorldContainer in different worlds
-    // anyways.
-    pub instances: FxHashMap<Identifier, Weak<RwLock<Instance>>>,
+    // telling them apart. We hope most servers are nice and don't do that. Perhaps this should be
+    // changed in the future to be configurable.
+    pub map: FxHashMap<WorldName, Weak<RwLock<World>>>,
 }
 
-impl InstanceContainer {
+impl Worlds {
     pub fn new() -> Self {
-        InstanceContainer::default()
+        Worlds::default()
     }
 
-    /// Get an instance (aka world) from the container.
+    /// Get a world instance from the container.
     ///
-    /// Returns `None` if none of the clients are in this instance.
-    pub fn get(&self, name: &InstanceName) -> Option<Arc<RwLock<Instance>>> {
-        self.instances.get(name).and_then(|world| world.upgrade())
+    /// Returns `None` if none of the clients are in the requested world.
+    pub fn get(&self, name: &WorldName) -> Option<Arc<RwLock<World>>> {
+        self.map.get(name).and_then(|world| world.upgrade())
     }
 
     /// Add an empty world to the container (unless it already exists) and
@@ -52,12 +52,12 @@ impl InstanceContainer {
     #[must_use = "the world will be immediately forgotten if unused"]
     pub fn get_or_insert(
         &mut self,
-        name: Identifier,
+        name: WorldName,
         height: u32,
         min_y: i32,
         default_registries: &RegistryHolder,
-    ) -> Arc<RwLock<Instance>> {
-        match self.instances.get(&name).and_then(|world| world.upgrade()) {
+    ) -> Arc<RwLock<World>> {
+        match self.map.get(&name).and_then(|world| world.upgrade()) {
             Some(existing_lock) => {
                 let existing = existing_lock.read();
                 if existing.chunks.height != height {
@@ -75,24 +75,40 @@ impl InstanceContainer {
                 existing_lock.clone()
             }
             _ => {
-                let world = Arc::new(RwLock::new(Instance {
+                let world = Arc::new(RwLock::new(World {
                     chunks: ChunkStorage::new(height, min_y),
                     entities_by_chunk: HashMap::new(),
                     entity_by_id: IntMap::default(),
                     registries: default_registries.clone(),
                 }));
-                debug!("Added new instance {name}");
-                self.instances.insert(name, Arc::downgrade(&world));
+                debug!("Added new world {name:?}");
+                self.map.insert(name, Arc::downgrade(&world));
                 world
             }
         }
     }
 }
 
-/// The name of the [`Instance`] (aka world/dimension) that the entity is in.
+/// The name of the [`World`] (aka dimension) that an entity is in.
 ///
-/// If two entities share the same instance name, we assume they're in the
-/// same instance.
+/// If two entities share the same world name, then Azalea assumes that they're
+/// in the same world.
 #[derive(Clone, Component, Debug, Deref, DerefMut, Eq, Hash, PartialEq)]
 #[doc(alias("worldname", "world name", "dimension"))]
-pub struct InstanceName(pub Identifier);
+pub struct WorldName(pub Identifier);
+impl WorldName {
+    /// Create a new `WorldName` with the given name.
+    pub fn new(name: &str) -> Self {
+        Self(Identifier::new(name))
+    }
+}
+impl Display for WorldName {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        self.0.fmt(f)
+    }
+}
+impl From<Identifier> for WorldName {
+    fn from(ident: Identifier) -> Self {
+        Self(ident)
+    }
+}
diff --git a/azalea-world/src/find_blocks.rs b/azalea-world/src/find_blocks.rs
index bd4ec09a..f8f1fd91 100644
--- a/azalea-world/src/find_blocks.rs
+++ b/azalea-world/src/find_blocks.rs
@@ -1,9 +1,9 @@
 use azalea_block::{BlockState, BlockStates};
 use azalea_core::position::{BlockPos, ChunkPos};
 
-use crate::{Chunk, ChunkStorage, Instance, iterators::ChunkIterator, palette::Palette};
+use crate::{Chunk, ChunkStorage, World, iterators::ChunkIterator, palette::Palette};
 
-impl Instance {
+impl World {
     /// Find the coordinates of a block in the world.
     ///
     /// Note that this is sorted by `x+y+z` and not `x^2+y^2+z^2` for
@@ -206,8 +206,8 @@ impl Iterator for FindBlocks<'_> {
 /// An optimized function for finding the block positions in a chunk that match
 /// the given block states.
 ///
-/// This is used internally by [`Instance::find_block`] and
-/// [`Instance::find_blocks`].
+/// This is used internally by [`World::find_block`] and
+/// [`World::find_blocks`].
 pub fn find_blocks_in_chunk(
     block_states: &BlockStates,
     chunk_pos: ChunkPos,
@@ -257,9 +257,9 @@ mod tests {
 
     #[test]
     fn find_block() {
-        let mut instance = Instance::default();
+        let mut world = World::default();
 
-        let chunk_storage = &mut instance.chunks;
+        let chunk_storage = &mut world.chunks;
         let mut partial_chunk_storage = PartialChunkStorage::default();
 
         // block at (17, 0, 0) and (0, 18, 0)
@@ -278,15 +278,15 @@ mod tests {
         chunk_storage.set_block_state(BlockPos { x: 17, y: 0, z: 0 }, BlockKind::Stone.into());
         chunk_storage.set_block_state(BlockPos { x: 0, y: 18, z: 0 }, BlockKind::Stone.into());
 
-        let pos = instance.find_block(BlockPos { x: 0, y: 0, z: 0 }, &BlockKind::Stone.into());
+        let pos = world.find_block(BlockPos { x: 0, y: 0, z: 0 }, &BlockKind::Stone.into());
         assert_eq!(pos, Some(BlockPos { x: 17, y: 0, z: 0 }));
     }
 
     #[test]
     fn find_block_next_to_chunk_border() {
-        let mut instance = Instance::default();
+        let mut world = World::default();
 
-        let chunk_storage = &mut instance.chunks;
+        let chunk_storage = &mut world.chunks;
         let mut partial_chunk_storage = PartialChunkStorage::default();
 
         // block at (-1, 0, 0) and (15, 0, 0)
@@ -305,7 +305,7 @@ mod tests {
         chunk_storage.set_block_state(BlockPos { x: -1, y: 0, z: 0 }, BlockKind::Stone.into());
         chunk_storage.set_block_state(BlockPos { x: 15, y: 0, z: 0 }, BlockKind::Stone.into());
 
-        let pos = instance.find_block(BlockPos { x: 0, y: 0, z: 0 }, &BlockKind::Stone.into());
+        let pos = world.find_block(BlockPos { x: 0, y: 0, z: 0 }, &BlockKind::Stone.into());
         assert_eq!(pos, Some(BlockPos { x: -1, y: 0, z: 0 }));
     }
 }
diff --git a/azalea-world/src/lib.rs b/azalea-world/src/lib.rs
index 7212c519..325d3b43 100644
--- a/azalea-world/src/lib.rs
+++ b/azalea-world/src/lib.rs
@@ -12,5 +12,12 @@ mod world;
 
 pub use bit_storage::BitStorage;
 pub use chunk_storage::{Chunk, ChunkStorage, PartialChunkStorage, Section};
-pub use container::{InstanceContainer, InstanceName};
+pub use container::{Worlds, WorldName};
 pub use world::*;
+
+#[deprecated = "renamed to `WorldName`."]
+pub type InstanceName = WorldName;
+#[deprecated = "renamed to `WorldContainer`."]
+pub type InstanceContainer = Worlds;
+#[deprecated = "renamed to `PartialWorld`."]
+pub type PartialInstance = PartialWorld;
diff --git a/azalea-world/src/world.rs b/azalea-world/src/world.rs
index a6ee1a63..74390ee4 100644
--- a/azalea-world/src/world.rs
+++ b/azalea-world/src/world.rs
@@ -14,30 +14,30 @@ use nohash_hasher::IntMap;
 
 use crate::{ChunkStorage, PartialChunkStorage};
 
-/// PartialInstances are usually owned by clients, and hold strong references to
-/// chunks and entities in [`Instance`]s.
+/// A reference to a slice of the world, as seen by an individual client.
 ///
-/// Basically, they hold the chunks and entities that are within render
-/// distance but can still access chunks and entities owned by other
-/// `PartialInstance`s that have the same `Instance`.
+/// A `PartialWorld` will typically be owned by a client, and it holds strong
+/// references to chunks and entities in a [`World`]s.
 ///
-/// This is primarily useful for having multiple clients in the same Instance.
-pub struct PartialInstance {
+/// In other words, this type holds the chunks and entities that are within
+/// render distance for a client. The same chunk/entity may be referenced by
+/// more than one `PartialWorld`.
+pub struct PartialWorld {
     pub chunks: PartialChunkStorage,
     /// Some metadata about entities, like what entities are in certain chunks.
     /// This does not contain the entity data itself, that's in the ECS.
     pub entity_infos: PartialEntityInfos,
 }
 
-impl PartialInstance {
+impl PartialWorld {
     pub fn new(chunk_radius: u32, owner_entity: Option<Entity>) -> Self {
-        PartialInstance {
+        PartialWorld {
             chunks: PartialChunkStorage::new(chunk_radius),
             entity_infos: PartialEntityInfos::new(owner_entity),
         }
     }
 
-    /// Clears the internal references to chunks in the PartialInstance and
+    /// Clears the internal references to chunks in the [`PartialWorld`] and
     /// resets the view center.
     pub fn reset(&mut self) {
         self.chunks = PartialChunkStorage::new(self.chunks.chunk_radius);
@@ -75,16 +75,21 @@ impl PartialEntityInfos {
     }
 }
 
-/// A world where the chunks are stored as weak pointers. This is used for
-/// shared worlds.
+/// A Minecraft world, sometimes referred to as a dimension.
 ///
-/// Also see [`PartialInstance`].
+/// This is the most commonly used type to interact with the world that a client
+/// is in. In here, all chunks are stored as weak pointers, which means that
+/// clients in different areas of the same world can share the same `World`
+/// instance.
 ///
-/// This is sometimes interchangeably called a "world". However, this type is
-/// called `Instance` to avoid colliding with the `World` type from Bevy ECS.
+/// Also see [`PartialWorld`].
+///
+/// Note that this is distinct from Bevy's `World` type, which contains all of
+/// the data for every client. When referring to the Bevy `World` within Azalea,
+/// the term "ECS" is generally used instead.
 #[derive(Debug, Default)]
-#[doc(alias("world", "dimension"))]
-pub struct Instance {
+#[doc(alias("instance", "dimension", "level"))]
+pub struct World {
     pub chunks: ChunkStorage,
 
     /// An index of all the entities we know are in the chunks of the world
@@ -101,7 +106,10 @@ pub struct Instance {
     pub registries: RegistryHolder,
 }
 
-impl Instance {
+#[deprecated = "renamed to `World`."]
+pub type Instance = World;
+
+impl World {
     /// Get the block at the given position, or `None` if it's outside of the
     /// world that we have loaded.
     pub fn get_block_state(&self, pos: BlockPos) -> Option<BlockState> {
@@ -131,17 +139,17 @@ impl Instance {
     }
 }
 
-impl Debug for PartialInstance {
+impl Debug for PartialWorld {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        f.debug_struct("PartialInstance")
+        f.debug_struct("PartialWorld")
             .field("chunks", &self.chunks)
             .field("entity_infos", &self.entity_infos)
             .finish()
     }
 }
 
-impl Default for PartialInstance {
-    /// Creates a completely self-contained `PartialInstance`. This is only for
+impl Default for PartialWorld {
+    /// Creates a completely self-contained [`PartialWorld`]. This is only for
     /// testing and shouldn't be used in actual code!
     fn default() -> Self {
         let chunk_storage = PartialChunkStorage::default();
@@ -153,7 +161,7 @@ impl Default for PartialInstance {
     }
 }
 
-impl From<ChunkStorage> for Instance {
+impl From<ChunkStorage> for World {
     /// Make an empty world from this `ChunkStorage`. This is meant to be a
     /// convenience function for tests.
     fn from(chunks: ChunkStorage) -> Self {