mcdex 0.1.0.dev0__py3-none-any.whl

mcdex/base/_chicken_sound_variant_id.py

@@ -0,0 +1,23 @@
+"""
+ChickenSoundVariantId pairs a chicken sound variant's unique name with the id a
+version of the game needs to identify it.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+from __future__ import annotations
+
+from . import GameId
+
+
+class ChickenSoundVariantId(GameId):
+  """
+  The id of a chicken sound variant in one version: its 'uniqueName', the same
+  in every version, and its 'minecraftId', what /summon takes for a chicken of
+  that sound variant in that version.
+
+  Implementation
+  --------------
+
+  All of it is 'GameId's: a 'ChickenSoundVariantId' is equal only to a
+  'ChickenSoundVariantId'.
+  """

mcdex/base/_chicken_variant_id.py

@@ -0,0 +1,23 @@
+"""
+ChickenVariantId pairs a chicken variant's unique name with the id a version of
+the game needs to identify it.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+from __future__ import annotations
+
+from . import GameId
+
+
+class ChickenVariantId(GameId):
+  """
+  The id of a chicken variant in one version: its 'uniqueName', the same in
+  every version, and its 'minecraftId', what /summon takes for a chicken of
+  that variant in that version.
+
+  Implementation
+  --------------
+
+  All of it is 'GameId's: a 'ChickenVariantId' is equal only to a
+  'ChickenVariantId'.
+  """

mcdex/base/_cow_sound_variant_id.py

@@ -0,0 +1,23 @@
+"""
+CowSoundVariantId pairs a cow sound variant's unique name with the id a version
+of the game needs to identify it.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+from __future__ import annotations
+
+from . import GameId
+
+
+class CowSoundVariantId(GameId):
+  """
+  The id of a cow sound variant in one version: its 'uniqueName', the same in
+  every version, and its 'minecraftId', what /summon takes for a cow of that
+  sound variant in that version.
+
+  Implementation
+  --------------
+
+  All of it is 'GameId's: a 'CowSoundVariantId' is equal only to a
+  'CowSoundVariantId'.
+  """

mcdex/base/_cow_variant_id.py

@@ -0,0 +1,22 @@
+"""
+CowVariantId pairs a cow variant's unique name with the id a version of the
+game needs to identify it.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+from __future__ import annotations
+
+from . import GameId
+
+
+class CowVariantId(GameId):
+  """
+  The id of a cow variant in one version: its 'uniqueName', the same in every
+  version, and its 'minecraftId', what /summon takes for a cow of that variant
+  in that version.
+
+  Implementation
+  --------------
+
+  All of it is 'GameId's: a 'CowVariantId' is equal only to a 'CowVariantId'.
+  """

mcdex/base/_damage_type_id.py

@@ -0,0 +1,21 @@
+"""
+DamageTypeId pairs a damage type's unique name with the id a version of the
+game needs to identify it.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+from __future__ import annotations
+
+from . import GameId
+
+
+class DamageTypeId(GameId):
+  """
+  The id of a damage type in one version: its 'uniqueName', the same in
+  every version, and its 'minecraftId', what /damage takes in that version.
+
+  Implementation
+  --------------
+
+  All of it is 'GameId's: a 'DamageTypeId' is equal only to a 'DamageTypeId'.
+  """

mcdex/base/_dimension_id.py

@@ -0,0 +1,21 @@
+"""
+DimensionId pairs a dimension's unique name with the id a version of the game
+needs to identify it.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+from __future__ import annotations
+
+from . import GameId
+
+
+class DimensionId(GameId):
+  """
+  The id of a dimension in one version: its 'uniqueName', the same in
+  every version, and its 'minecraftId', what /execute in takes in that version.
+
+  Implementation
+  --------------
+
+  All of it is 'GameId's: a 'DimensionId' is equal only to a 'DimensionId'.
+  """

mcdex/base/_effect_id.py

@@ -0,0 +1,21 @@
+"""
+EffectId pairs an effect's unique name with the id a version of the game
+needs to identify it.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+from __future__ import annotations
+
+from . import GameId
+
+
+class EffectId(GameId):
+  """
+  The id of an effect in one version: its 'uniqueName', the same in
+  every version, and its 'minecraftId', what '/effect' takes in that version.
+
+  Implementation
+  --------------
+
+  All of it is 'GameId's: an 'EffectId' is equal only to an 'EffectId'.
+  """

mcdex/base/_enchantment_id.py

@@ -0,0 +1,22 @@
+"""
+EnchantmentId pairs an enchantment's unique name with the id a version of the
+game needs to identify it.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+from __future__ import annotations
+
+from . import GameId
+
+
+class EnchantmentId(GameId):
+  """
+  The id of an enchantment in one version: its 'uniqueName', the same in
+  every version, and its 'minecraftId', what '/enchant' takes in that version.
+
+  Implementation
+  --------------
+
+  All of it is 'GameId's: an 'EnchantmentId' is equal only to an
+  'EnchantmentId'.
+  """

mcdex/base/_entity_id.py

@@ -0,0 +1,35 @@
+"""
+EntityId pairs an entity's unique name with the id a version of the game
+needs to identify it.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+from __future__ import annotations
+
+from . import GameId
+
+
+class EntityId(GameId):
+  """
+  A user of mcdex names an entity once, by its unique name, as
+  'wither_skeleton', and each version of the game needs its own id for
+  it: what '/summon' takes. 'EntityId' holds the two: 'uniqueName', the
+  same in every version, and 'minecraftId', all that one version needs
+  to identify the entity, as one string in the notation of its era:
+
+    EntityId('creeper', 'Creeper')                    # 1.7.2 to 1.10.2
+    EntityId('creeper', 'minecraft:creeper')          # since 1.11
+
+  Where an old version told entities apart by their data, the id carries
+  that data after the name, as /summon takes it: the wither skeleton of
+  1.10.2 is a skeleton of type 1, 'Skeleton{SkeletonType:1}', and a
+  spruce boat before 1.21.2 'minecraft:boat{Type:"spruce"}'.
+
+  An 'EntityId' is never an 'ItemId', even where the two have the same
+  text: the pig and its spawn egg are different things.
+
+  Implementation
+  --------------
+
+  All of it is 'GameId's: an 'EntityId' is equal only to an 'EntityId'.
+  """

mcdex/base/_equipment_slot.py

@@ -0,0 +1,34 @@
+"""
+EquipmentSlot enumerates the slots an entity wears or holds an item in.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+from __future__ import annotations
+
+from worktoy.keenum import KeeNum, Kee
+
+
+class EquipmentSlot(KeeNum):
+  """
+  An item goes to one slot when an entity equips it: the elytra to the
+  chest, a helmet to the head, a shield to the offhand, horse armor to a
+  horse's body, a saddle to its saddle, and every other item to the main
+  hand. EquipmentSlot enumerates those slots, in the order of the game's
+  own enumeration as of 26.3, each holding the name the game serializes
+  it by:
+
+    EquipmentSlot('chest') is EquipmentSlot.CHEST
+
+  The offhand arrived in 1.9, the body in 1.20.5 and the saddle in
+  1.21.5; before each, an item that would go there went to the main
+  hand.
+  """
+
+  MAINHAND = Kee[str]('mainhand')
+  OFFHAND = Kee[str]('offhand')
+  FEET = Kee[str]('feet')
+  LEGS = Kee[str]('legs')
+  CHEST = Kee[str]('chest')
+  HEAD = Kee[str]('head')
+  BODY = Kee[str]('body')
+  SADDLE = Kee[str]('saddle')

mcdex/base/_frog_variant_id.py

@@ -0,0 +1,22 @@
+"""
+FrogVariantId pairs a frog variant's unique name with the id a version of the
+game needs to identify it.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+from __future__ import annotations
+
+from . import GameId
+
+
+class FrogVariantId(GameId):
+  """
+  The id of a frog variant in one version: its 'uniqueName', the same in every
+  version, and its 'minecraftId', what /summon takes for a frog of that variant
+  in that version.
+
+  Implementation
+  --------------
+
+  All of it is 'GameId's: a 'FrogVariantId' is equal only to a 'FrogVariantId'.
+  """

mcdex/base/_game_id.py

@@ -0,0 +1,88 @@
+"""
+GameId pairs a thing's unique name with the id a version of the game
+needs to identify it: the shared code of each kind's own id class.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from worktoy.dispatch import overload
+from worktoy.desc import FixBox
+from worktoy.mcls import BaseObject
+
+if TYPE_CHECKING:  # pragma: no cover, no mutate
+  from typing import Any, TypeAlias
+
+  Key: TypeAlias = tuple[str, str]
+
+
+class GameId(BaseObject):
+  """
+  The id of one thing of the game in one version: its 'uniqueName', the
+  same in every version, and its 'minecraftId', all that version needs
+  to identify it, as one string in the notation of its era. Each kind of
+  thing has its own subclass, as 'EntityId' and 'BlockId', and an id of
+  one kind is never equal to an id of another, even with the same text:
+  the pig and its spawn egg are different things.
+
+  Implementation
+  --------------
+
+  'uniqueName' and 'minecraftId' are 'FixBox[str]', written once by the
+  constructor, which refuses an empty one with 'ValueError'. The text of
+  an id is its 'minecraftId'. Equality and hash compare the class and
+  both strings; anything but an id of the same class compares as
+  'NotImplemented'.
+  """
+
+  # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+  #  NAMESPACE  # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+  # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+
+  #  Public Variables
+  uniqueName = FixBox[str]()
+  minecraftId = FixBox[str]()
+
+  # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+  #  Python API   # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+  # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+
+  def __str__(self, ) -> str:
+    """The 'minecraftId', as 'minecraft:wool:6'."""
+    return self.minecraftId
+
+  def __repr__(self, ) -> str:
+    """"BlockId('pink_wool', 'minecraft:wool:6')", which evaluates back."""
+    return '%s(%r, %r)' % (type(self).__name__, *self._key())
+
+  def __eq__(self, other: Any) -> bool:
+    if type(other) is type(self):
+      return self._key() == other._key()
+    return NotImplemented
+
+  def __hash__(self, ) -> int:
+    return hash((type(self).__name__,) + self._key())
+
+  # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+  #  CONSTRUCTORS   # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+  # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+
+  @overload(str, str)
+  def __init__(self, uniqueName: str, minecraftId: str) -> None:
+    for name_, value_ in (('uniqueName', uniqueName),
+                          ('minecraftId', minecraftId)):
+      if not value_:
+        infoSpec = """%s() received an empty '%s'"""
+        raise ValueError(infoSpec % (type(self).__name__, name_))
+    self.uniqueName = uniqueName
+    self.minecraftId = minecraftId
+
+  # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+  #  DOMAIN SPECIFIC  # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+  # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+
+  def _key(self, ) -> Key:
+    """The unique name and the minecraft id, for comparisons and hash."""
+    return (self.uniqueName, self.minecraftId)

mcdex/base/_game_rule_id.py

@@ -0,0 +1,21 @@
+"""
+GameRuleId pairs a game rule's unique name with the id a version of the game
+needs to identify it.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+from __future__ import annotations
+
+from . import GameId
+
+
+class GameRuleId(GameId):
+  """
+  The id of a game rule in one version: its 'uniqueName', the same in
+  every version, and its 'minecraftId', what '/gamerule' takes in that version.
+
+  Implementation
+  --------------
+
+  All of it is 'GameId's: a 'GameRuleId' is equal only to a 'GameRuleId'.
+  """

mcdex/base/_item_id.py

@@ -0,0 +1,98 @@
+"""
+ItemId pairs an item's unique name with the id a version of the game
+needs to identify it.
+"""
+#  Apache-2.0 license
+#  Copyright (c) 2026 Asger Jon Vistisen
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from worktoy.dispatch import overload
+from worktoy.desc import FixBox
+from worktoy.mcls import BaseObject
+
+if TYPE_CHECKING:  # pragma: no cover, no mutate
+  from typing import Any, TypeAlias
+
+  Key: TypeAlias = tuple[str, str]
+
+
+class ItemId(BaseObject):
+  """
+  A user of mcdex names an item once, by its unique name, as
+  'pink_wool', and each version of the game needs its own id for it.
+  'ItemId' holds the two: 'uniqueName', the same in every version, and
+  'minecraftId', all that one version needs to identify the item, as
+  one string in the notation of its era:
+
+    ItemId('pink_wool', '35:6')                 # before 1.7.2
+    ItemId('pink_wool', 'minecraft:wool:6')     # 1.7.2 to 1.12.2
+    ItemId('pink_wool', 'minecraft:pink_wool')  # since 1.13
+
+  Before 1.7.2 the game had only numbers, the id and the meta value;
+  then names, with the meta where it told items apart; and since 1.13
+  the name alone. A meta that is only damage, as the elytra's was, is no
+  part of the id. A registry name has no ':' in its path, so a trailing
+  ':6' is always the meta. An item the game told apart by NBT carries it
+  after the name, as the /give command takes it: a creeper spawn egg of
+  1.12.2 is 'minecraft:spawn_egg{EntityTag:{id:"minecraft:creeper"}}'.
+
+  Implementation
+  --------------
+
+  'uniqueName' and 'minecraftId' are 'FixBox[str]', written once by the
+  constructor, which refuses an empty one with 'ValueError'. The text of
+  an id is its 'minecraftId'. Equality and hash compare both strings;
+  anything but an 'ItemId' compares as 'NotImplemented'.
+  """
+
+  # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+  #  NAMESPACE  # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+  # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+
+  #  Public Variables
+  uniqueName = FixBox[str]()
+  minecraftId = FixBox[str]()
+
+  # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+  #  Python API   # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+  # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+
+  def __str__(self, ) -> str:
+    """The 'minecraftId', as 'minecraft:wool:6'."""
+    return self.minecraftId
+
+  def __repr__(self, ) -> str:
+    """"ItemId('pink_wool', 'minecraft:wool:6')", which evaluates back."""
+    return '%s(%r, %r)' % (type(self).__name__, *self._key())
+
+  def __eq__(self, other: Any) -> bool:
+    if isinstance(other, ItemId):
+      return self._key() == other._key()
+    return NotImplemented
+
+  def __hash__(self, ) -> int:
+    return hash(self._key())
+
+  # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+  #  CONSTRUCTORS   # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+  # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+
+  @overload(str, str)
+  def __init__(self, uniqueName: str, minecraftId: str) -> None:
+    for name_, value_ in (('uniqueName', uniqueName),
+                          ('minecraftId', minecraftId)):
+      if not value_:
+        infoSpec = """%s() received an empty '%s'"""
+        raise ValueError(infoSpec % (type(self).__name__, name_))
+    self.uniqueName = uniqueName
+    self.minecraftId = minecraftId
+
+  # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+  #  DOMAIN SPECIFIC  # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+  # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+
+  def _key(self, ) -> Key:
+    """The unique name and the minecraft id, for comparisons and hash."""
+    return (self.uniqueName, self.minecraftId)