From 3320a21d3c7dfe97a11cf4483dfb95ed47d03217 Mon Sep 17 00:00:00 2001 From: liach <7806504+liach@users.noreply.github.com> Date: Tue, 8 Jun 2021 18:14:21 -0500 Subject: [PATCH] Barebone javadoc for brain, explains why (#2475) closes #2210, feel free to ask for more Co-authored-by: liach Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- .../net/minecraft/entity/ai/brain/Brain.mapping | 13 +++++++++++++ .../entity/ai/brain/MemoryModuleType.mapping | 6 ++++++ .../entity/ai/brain/sensor/Sensor.mapping | 5 +++++ .../minecraft/entity/ai/brain/package-info.java | 14 ++++++++++++++ .../net/minecraft/entity/ai/goal/package-info.java | 13 +++++++++++++ 5 files changed, 51 insertions(+) create mode 100644 src/packageDocs/java/net/minecraft/entity/ai/brain/package-info.java create mode 100644 src/packageDocs/java/net/minecraft/entity/ai/goal/package-info.java diff --git a/mappings/net/minecraft/entity/ai/brain/Brain.mapping b/mappings/net/minecraft/entity/ai/brain/Brain.mapping index 998e871bc3..c7567911a4 100644 --- a/mappings/net/minecraft/entity/ai/brain/Brain.mapping +++ b/mappings/net/minecraft/entity/ai/brain/Brain.mapping @@ -1,4 +1,17 @@ CLASS net/minecraft/class_4095 net/minecraft/entity/ai/brain/Brain + COMMENT A brain is associated with each living entity. + COMMENT + COMMENT

A brain has {@linkplain #memories memories}, {@linkplain #sensors sensors}, + COMMENT and {@linkplain #tasks tasks}. In general, the brain can use sensors to refresh + COMMENT the memories over time, and the memories can be shared by different tasks, + COMMENT which can reduce duplicate calculation. For instance, instead of having each + COMMENT task scan for the player, the memories can hold information about nearby player, + COMMENT and the task can choose to run or not accordingly. + COMMENT + COMMENT

To construct a brain, you need to specify the memory (module) types and + COMMENT sensors present in a brain, and then you can add individual tasks. + COMMENT + COMMENT @see LivingEntity#brain FIELD field_18322 memories Ljava/util/Map; FIELD field_18323 sensors Ljava/util/Map; FIELD field_18324 tasks Ljava/util/Map; diff --git a/mappings/net/minecraft/entity/ai/brain/MemoryModuleType.mapping b/mappings/net/minecraft/entity/ai/brain/MemoryModuleType.mapping index 5e9502a2fd..a9f1979bca 100644 --- a/mappings/net/minecraft/entity/ai/brain/MemoryModuleType.mapping +++ b/mappings/net/minecraft/entity/ai/brain/MemoryModuleType.mapping @@ -1,4 +1,10 @@ CLASS net/minecraft/class_4140 net/minecraft/entity/ai/brain/MemoryModuleType + COMMENT A memory module type represents a type of data stored in a brain. The memory + COMMENT data can be shared by different tasks once they are updated by a sensor or + COMMENT created by some task. This can avoid some redundant calculations. + COMMENT + COMMENT @see Brain#memories + COMMENT @see Memory FIELD field_24668 codec Ljava/util/Optional; METHOD (Ljava/util/Optional;)V ARG 1 codec diff --git a/mappings/net/minecraft/entity/ai/brain/sensor/Sensor.mapping b/mappings/net/minecraft/entity/ai/brain/sensor/Sensor.mapping index 02db8e6c99..74b3a0ab08 100644 --- a/mappings/net/minecraft/entity/ai/brain/sensor/Sensor.mapping +++ b/mappings/net/minecraft/entity/ai/brain/sensor/Sensor.mapping @@ -1,4 +1,9 @@ CLASS net/minecraft/class_4148 net/minecraft/entity/ai/brain/sensor/Sensor + COMMENT A sensor can update memories over time in a brain. The sensor's computation + COMMENT replaces that of individual tasks, so that it is more efficient than the goal + COMMENT system. + COMMENT + COMMENT @see Brain#sensors FIELD field_18463 lastSenseTime J FIELD field_18464 senseInterval I FIELD field_19294 RANDOM Ljava/util/Random; diff --git a/src/packageDocs/java/net/minecraft/entity/ai/brain/package-info.java b/src/packageDocs/java/net/minecraft/entity/ai/brain/package-info.java new file mode 100644 index 0000000000..9aedaad288 --- /dev/null +++ b/src/packageDocs/java/net/minecraft/entity/ai/brain/package-info.java @@ -0,0 +1,14 @@ +/* + * This file is free for everyone to use under the Creative Commons Zero license. + */ + +/** + * This and its subpackages make up the brain system used by some modern Minecraft entities, + * such as villagers, piglins, and axolotls. + * + *

Compared to {@linkplain net.minecraft.entity.ai.goal the goal system}, the brain system's + * main advantage is that it allows sharing of certain expensive calculation results in the + * form of memory by the individual tasks. + */ + +package net.minecraft.entity.ai.brain; diff --git a/src/packageDocs/java/net/minecraft/entity/ai/goal/package-info.java b/src/packageDocs/java/net/minecraft/entity/ai/goal/package-info.java new file mode 100644 index 0000000000..829910ff0a --- /dev/null +++ b/src/packageDocs/java/net/minecraft/entity/ai/goal/package-info.java @@ -0,0 +1,13 @@ +/* + * This file is free for everyone to use under the Creative Commons Zero license. + */ + +/** + * The basic AI system for Minecraft living entities. + * + *

This has been the dominant AI system in Minecraft since 1.8. In 1.14, with the update + * on villagers, a new {@linkplain net.minecraft.entity.ai.brain brain system} has been + * introduced. + */ + +package net.minecraft.entity.ai.goal;