♻️ Give names to almost all structs

README.md

@@ -3,6 +3,15 @@ The vanilla definition files using the schema format, [mcdoc](https://github.com
 
 Format documentation: https://spyglassmc.com/user/mcdoc/
 
+Informal linting rules:
+- Avoid unnecessary/implied doc comments and doc comment contents.
+- If a string union changes between mc updates use a string enum instead.
+- Always name structs that are dispatched to.
+- Always name nested structs unless they are a string map.
+- Avoid repetitive code.
+- Avoid nesting structs further than 3 levels deep.
+- Prefer descriptive, useful, & succinct struct/type alias names, otherwise provide ample dev comments.
+
 Based on original schema repositories:
 - [mc-nbtdoc](https://github.com/Yurihaia/mc-nbtdoc)
 - [minecraft-schemas](https://github.com/misode/minecraft-schemas)

java/assets/atlas.mcdoc

@@ -40,8 +40,8 @@ struct FilterPattern {
 dispatch minecraft:sprite_source[paletted_permutations] to struct PalettedPermutations {
  textures: [#[id="texture"] string],
  palette_key: #[id="texture"] string,
- permutations: struct {
- [string]: #[id="texture"] string, // TODO
+ permutations: struct PermutationsMap {
+ [#[permutation(definition=true)] string]: #[id="texture"] string,
  },
 }
 

java/assets/block_definition.mcdoc → java/assets/block_state_definition.mcdoc

@@ -1,22 +1,22 @@
-type BlockDefinition = (
- struct {
- variants: struct {
- [string]: ModelVariant,
+type BlockStateDefinition = (
+ struct BlockStateDefinitionVariant {
+ variants: struct BlockStateDefinitionVariantMap {
+ [string]: ModelVariant, // TODO: block state key
  },
  } |
- struct {
- multipart: [struct {
+ struct BlockStateDefinitionMultipart {
+ multipart: [struct BlockStateDefinitionMultipartEntry {
  /// One condition or an array where at least one condition must apply.
  when?: MultiPartCondition,
  apply: ModelVariant,
  }],
  } |
 )
-dispatch minecraft:resource[block_state] to BlockDefinition
+dispatch minecraft:resource[block_state] to BlockStateDefinition
 
 type ModelVariant = (
  ModelVariantBase |
- [struct {
+ [struct WeightedModelVariant {
  ...ModelVariantBase,
  weight?: int @ 1..,
  }] |
@@ -31,10 +31,10 @@ struct ModelVariantBase {
 }
 
 type MultiPartCondition = (
- struct {
+ struct MultiPartAlternatives {
  OR: [MultiPartCondition],
  } |
- struct {
- [string]: string,
+ struct MultiPartAnd {
+ [string]: string, // TODO: block state key
  } |
 )

java/assets/credits.mcdoc

@@ -1,11 +1,11 @@
-type Credits = [struct {
+type Credits = [struct CreditsCompanySegment {
  /// Company segment.
  section: string,
- disciplines: [struct {
- discipline: (string | ""),
- titles: [struct {
+ disciplines: [struct CreditsDiscipline {
+ discipline: (string @ 1.. | string @ 0),
+ titles: [struct CreditsJobTitle {
  title: string,
- /// People with the title.
+ /// Employees with the title.
  names: [string],
  }],
  }],

java/assets/font.mcdoc

@@ -43,7 +43,7 @@ dispatch minecraft:glyph_provider[legacy_unicode] to struct LegacyUnicodeProvide
 dispatch minecraft:glyph_provider[unihex] to struct UnihexProvider {
  /// ZIP archive containing one or more *.hex files (files in archive with different extensions are ignored).
  hex_file: string, // TODO
- size_overrides?: struct {
+ size_overrides?: struct UnihexSizeOverrides {
  /// Minimum in codepoint range (inclusive).
  from: string, // TODO: codepoint; "\u3001"
  /// Maximum in codepoint range (inclusive).

java/assets/model.mcdoc

@@ -4,52 +4,46 @@ dispatch minecraft:resource[model] to struct Model {
  parent?: #[id="model"] string,
  ambientocclusion?: boolean,
  gui_light?: ("front" | "side"),
- textures?: struct {
- [string]: #[id="texture"] string, // TODO
+ textures?: struct ModelTextures {
+ [#[model_texture(definition=true)] string]: #[id="texture"] string,
  },
  particle?: #[id="texture"] string,
  elements?: [ModelElement],
- display?: struct {
- [ItemTransformType]: ItemTransform,
+ display?: struct ModelDisplay {
+ [ItemTransformType]: struct ItemTransform {
+ rotation?: [float] @ 3,
+ translation?: [float @ -80..80] @ 3,
+ scale?: [float @ -4..4] @ 3,
+ },
  },
- overrides?: [ModelOverride],
+ #[model_override] // Currently unimplemented attribute to help with sorting rules.
+ overrides?: [struct ModelOverride {
+ #[model_override(predicate=true)] // Also unimplemented.
+ predicate: struct ModelOverridePredicates {
+ [Predicates]: float,
+ },
+ model: #[id="model"] string,
+ }],
 }
 
 struct ModelElement {
  from: [float @ -16..32] @ 3,
  to: [float @ -16..32] @ 3,
- faces: struct {
- [Direction]: ModelElementFace,
+ faces: struct ModelElementFaceMap {
+ [Direction]: struct ModelElementFace {
+ texture: #[model_texture] string,
+ uv?: [float] @ 4,
+ cullface?: Direction,
+ rotation?: int,
+ tintindex?: int,
+ },
  },
- rotation?: ModelElementRotation,
- shade?: boolean,
-}
-
-struct ModelElementFace {
- texture: string, // TODO
- uv?: [float] @ 4,
- cullface?: Direction,
- rotation?: int,
- tintindex?: int,
-}
-
-struct ModelElementRotation {
- origin: [float] @ 3,
- axis: Axis,
- angle: (-45.0 | -22.5 | 0.0 | 22.5 | 45.0),
-}
-
-struct ItemTransform {
- rotation?: [float] @ 3,
- translation?: [float @ -80..80] @ 3,
- scale?: [float @ -4..4] @ 3,
-}
-
-struct ModelOverride {
- predicate: struct {
- [Predicates]: float,
+ rotation?: struct ModelElementRotation {
+ origin: [float] @ 3,
+ axis: Axis,
+ angle: (-45.0 | -22.5 | 0.0 | 22.5 | 45.0),
  },
- model: #[id="model"] string,
+ shade?: boolean,
 }
 
 enum(string) Axis {

java/assets/texture_meta.mcdoc

@@ -1,5 +1,5 @@
 dispatch minecraft:resource[texture_meta] to struct TextureMeta {
- animation: struct {
+ animation: struct TextureAnimation {
  /// If true, additional frames will be generated between frames with a frame time greater than 1 between them. Defaults to false.
  interpolate?: boolean,
  /// The width of the tile, as a direct ratio rather than in pixels. Can be used by resource packs to have frames that are not perfect squares.
@@ -10,7 +10,7 @@ dispatch minecraft:resource[texture_meta] to struct TextureMeta {
  frametime?: int,
  /// Defaults to displaying all the frames from top to bottom.
  frames?: [
- (struct {
+ (struct TextureAnimationFrame {
  /// A number corresponding to position of a frame from the top, with the top frame being 0.
  index: int,
  /// The time in ticks to show this frame, overriding `frametime` above.
@@ -20,12 +20,12 @@ dispatch minecraft:resource[texture_meta] to struct TextureMeta {
  )],
  },
  /// Only available for villager textures.
- villager: struct {
+ villager: struct VillagerTextureMeta {
  /// Determines whether the villager's 'profession' hat layer should allow the 'type' hat layer to render or not. If this mcmeta is undefined the default is used.
  hat?: ("full" | "partial")
  },
  /// Only available for colormaps.
- texture: struct {
+ texture: struct ColormapTextureMeta {
  /// Causes the texture to blur when viewed from close up. Defaults to false.
  blur?: boolean,
  /// Causes the texture to stretch instead of tiling in cases where it otherwise would, such as on the shadow. Defaults to false.

java/data/advancement/mod.mcdoc

@@ -8,7 +8,7 @@ dispatch minecraft:resource[advancement] to struct Advancement {
  /// Circular references cause a loading failure.
  parent?: #[id="advancement"] string,
  /// If `requirements` is not defined, all defined criteria will be required.
- criteria: struct {
+ criteria: struct AdvancementCriteriaMap {
  [#[criterion(definition=true)] string]: AdvancementCriterion,
  },
  /// Contains all of the `criteria` keys.

java/data/advancement/predicate.mcdoc

@@ -9,7 +9,7 @@ use ::java::server::world::item::CustomData
 use super::super::util::MinMaxBounds
 
 type ItemPredicate = (
- #[until="1.20.5"] struct {
+ #[until="1.20.5"] struct PreComponentsItemPredicate {
  #[until="1.17"]
  item?: #[id="item"] string,
  #[since="1.17"]
@@ -21,7 +21,7 @@ type ItemPredicate = (
  stored_enchantments?: [EnchantmentPredicate],
  nbt?: #[nbt=minecraft:item[[item]]] string,
  } |
- #[since="1.20.5"] struct {
+ #[since="1.20.5"] struct PostComponentsItemPredicate {
  items?: (#[id(registry="item",tags="allowed")] string | [#[id="item"] string]),
  count?: MinMaxBounds<int>,
  components?: DataComponentPredicate,
@@ -125,13 +125,14 @@ struct FluidPredicate {
  tag?: #[id(registry="fluid",tags="implicit")] string,
  #[since="1.20.5"]
  fluids?: (#[id(registry="fluid",tags="allowed")] string | [#[id="fluid"] string]),
- state?: struct {
- [string]: (MinMaxBounds<int> | boolean | string), // TODO
+ // TODO (mcdoc:fluid_states[[fluids]])
+ state?: struct FluidPredicateState {
+ [string]: (MinMaxBounds<int> | boolean | string),
  },
 }
 
 struct LocationPredicate {
- position?: struct {
+ position?: struct LocationPredicatePosition {
  x?: MinMaxBounds<float>,
  y?: MinMaxBounds<float>,
  z?: MinMaxBounds<float>,
@@ -154,8 +155,8 @@ struct LocationPredicate {
  structures?: (#[id=(registry="worldgen/structure",tags=allowed)] string | [#[id="worldgen/structure"] string]),
  dimension?: #[id="dimension"] string,
  /// Calculated using: `max(sky-darkening, block)`.
- light?: struct {
- light?: MinMaxBounds<int @ 0..15>,
+ light?: struct LocationPredicateLight {
+ light?: MinMaxBounds<int @ 0..15>, // :mojank:
  },
  block?: BlockPredicate,
  fluid?: FluidPredicate,
@@ -189,7 +190,7 @@ struct EntityPredicate {
  location?: LocationPredicate,
  distance?: DistancePredicate,
  flags?: EntityFlagsPredicate,
- equipment?: struct {
+ equipment?: struct EntityEquipment {
  [EquipmentSlot]: ItemPredicate,
  },
  #[until="1.19"]
@@ -209,11 +210,11 @@ struct EntityPredicate {
  lightning_bolt?: LightningBoltPredicate,
  #[until="1.19"]
  catType?: string,
- effects?: struct {
+ effects?: struct EntityEffects {
  [#[id="mob_effect"] string]: MobEffectPredicate,
  },
  #[since="1.20.5"]
- slots?: struct {
+ slots?: struct EntityInventorySlots {
  [#[item_slots] string]: ItemPredicate,
  },
  #[since="1.21"]
@@ -302,9 +303,9 @@ dispatch minecraft:entity_sub_predicate[lightning] to struct LightningBoltPredic
 }
 
 dispatch minecraft:entity_sub_predicate[player] to struct PlayerPredicate {
- advancements?: struct {
- [#[id="advancement"] string]: (boolean | struct {
- [string]: boolean,
+ advancements?: struct PlayerAdvancements {
+ [#[id="advancement"] string]: (boolean | struct PlayerAdvancementCriteria {
+ [string]: boolean, // TODO: This should use `#[criterion]`, but it's not supported yet.
  }),
  },
  gamemode?: (
@@ -313,7 +314,7 @@ dispatch minecraft:entity_sub_predicate[player] to struct PlayerPredicate {
  ),
  /// Experience/XP level.
  level?: MinMaxBounds<int>,
- recipes?: struct {
+ recipes?: struct PlayerRecipes {
  [#[id="recipe"] string]: boolean,
  },
  stats?: [StatisticPredicate],
@@ -382,7 +383,7 @@ struct DamagePredicate {
 
 struct DamageSourcePredicate {
  #[until="1.19.4"]
- ...struct {
+ ...struct DamageSourceFlags {
  is_explosion?: boolean,
  is_fire?: boolean,
  is_magic?: boolean,

java/data/advancement/trigger.mcdoc

@@ -189,7 +189,7 @@ dispatch minecraft:trigger[impossible] to TriggerBase
 
 dispatch minecraft:trigger[inventory_changed] to struct InventoryChanged {
  ...TriggerBase,
- slots?: struct {
+ slots?: struct InventoryChangedSlots {
  /// Amount of empty slots.
  empty?: MinMaxBounds<int>,
  /// Amount of occupied slots.
@@ -335,7 +335,7 @@ dispatch minecraft:trigger[ride_entity_in_lava] to struct RideEntityInLava {
 #[until="1.16"]
 dispatch minecraft:trigger[safely_harvest_honey] to struct SafelyHarvestHoney {
  ...TriggerBase,
- block?: struct {
+ block?: struct HoneyHarvestedBlock {
  block?: #[id="block"] string,
  tag?: #[id(registry="block",tags="implicit")] string,
  },

java/data/enchantment.mcdoc

@@ -40,7 +40,7 @@ dispatch minecraft:resource[enchantment] to struct Enchantment {
  /// The effective fee is multiplied by the level of the Enchantment.
  anvil_cost: int @ 0..,
  slots: [AttributeSlot],
- effects?: struct {
+ effects?: struct EnchantmentEffects {
  [#[id="enchantment_effect_component_type"] string]?: minecraft:effect_component[[%key]],
  },
 }

java/data/loot/condition.mcdoc

@@ -29,9 +29,8 @@ dispatch minecraft:loot_condition[all_of] to struct AllOf {
 
 dispatch minecraft:loot_condition[block_state_property] to struct BlockStateProperty {
  block: #[id="block"] string,
- properties?: struct { // TODO: was this optional in 1.20.2 and before? (wasn't codecified yet)
- [string]: string, // TODO
- },
+ // TODO: was this optional in 1.20.2 and before? (wasn't codecified yet)
+ properties?: mcdoc:block_states[[block]],
 }
 
 dispatch minecraft:loot_condition[damage_source_properties] to struct DamageSourceProperties {

java/data/loot/function.mcdoc

@@ -46,7 +46,7 @@ dispatch minecraft:loot_function[copy_name] to struct CopyName {
 
 struct CopyNbt {
  source: NbtProvider,
- ops: [(struct {
+ ops: [(struct CopyNbtOperation {
  source: #[nbt_path] string, // TODO
  target: (
  #[until="1.20.5"] #[nbt_path=minecraft:item[%fallback]] string |
@@ -377,7 +377,7 @@ dispatch minecraft:loot_function[set_count] to struct SetCount {
 }
 
 /// Sets the durability of applicable items.
-dispatch minecraft:loot_function[set_damage] to struct {
+dispatch minecraft:loot_function[set_damage] to struct SetDamage {
  /// Decimal percentage. Can be negative when used in combination with `add`.
  damage: (
  #[until="1.17"] RandomValueBounds |
@@ -479,7 +479,7 @@ dispatch minecraft:loot_function[set_stew_effect] to struct SetStewEffect {
 dispatch minecraft:loot_function[set_fireworks] to struct SetFireworks {
  /// If omitted, the flight duration of the item is left untouched - or set to 0 if the component did not exist before.
  flight_duration?: int @ 0..255,
- explosions?: struct {
+ explosions?: struct FireworkExplosions {
  values: [minecraft:data_component[firework_explosion]],
  ...ListOperation,
  },