gunivers/bookshelf

Bookshelf (formerly known as Gunivers Libs) is a user-friendly modular library datapack, crafted to assist mapmakers in effortlessly implementing intricate systems within their maps.

     

🕵️‍♂️ What is Bookshelf?

Bookshelf (formerly known as Gunivers Libs) is a user-friendly modular library datapack, crafted to assist mapmakers in effortlessly implementing intricate systems within their maps.

🎬 Watch presentation video

🛠️ Key features

🧮 Mathematical functions: sin, cos, exp, log, sqrt...

🖥️ Bitwise functions: and, or, xor, not, msb...

🏷️ ID system: easily identify entities.

🔗 Link entities: link positions and rotations between entities and create coherent structures!

🏃 Move and vectors: give customized trajectories to entities, which can bounce on blocks and more...

❤️ Health management: easily modify player health!

🧱 Block management: get and manipulate blocks (supports BlockStates and NBT)!

And much more...

Motivation

As developers, we recognize the importance of using libraries to save time and avoid reinventing the wheel. Unfortunately, we've noticed that mapmakers within the Minecraft community are often unfamiliar with this concept.

That's why we started this project, to introduce a variety of reusable tools and try to convice mapmakers to embrace the use of libraries.

While we strive to keep these modules as much optimized and accurate as possible, our main goal is to offer a wide range of features and provide tools that are both easy to use and install. Therefore, we will always prioritize accessibility above everything else.

Contribution

👉 Please refer to the contribution docs for more information

Anyone can contribute to this repository. Please do so by posting issues when you've found something that is unexpected or sending a pull request for improvements. If you have any doubts related to the project or want to discuss something, then join our Discord server.

bookshelf's Issues

`bs.random`: Monte Carlo algorithms for random generation in distribution

Implement the monte-carlo algorithm in order to generate random number according to a given distribution.

Note

Existing related datapack:
https://github.com/Aeldrion/Minecraft-Random

Add `bs.vector:cross_product`

Create a function that perform a cross product between two vectors stored in bs.vecotr.[x,y,z] and bs.in.[0,1,2]. It will then return a vector on bs.out.[0,1,2] and it's norm on bs.out.3

Cross product formula:

$$ \begin{pmatrix} x1\\ y1\\ z1 \end{pmatrix} \times \begin{pmatrix} x2\\ y2\\ z2 \end{pmatrix} = \begin{pmatrix} y1 * z2 - z1 * y2\\ z1 * x2 - x1 * z2\\ x1 * y2 - y1 * x2 \end{pmatrix} $$

Add to this function an option that allow to automatically normalize the vectors first

Create `bs.location` score swapping

These functions only allow to quickly transfer values from/to location objectives.

• bs.loc:swap_inputs will perform bs.loc.[x,y,z] <-> bs.in.[0,1,2]
• bs.loc:from_vec will perform bs.vec.[x,y,z] -> bs.loc.[x,y,z]
• bs.loc:from_outputs will perform bs.out.[0,1,2] -> bs.loc.[x,y,z]

`bs.time:get` does not work

At a first look, it seems that this loot table is outdated: https://github.com/Gunivers/Bookshelf/blob/master/datapacks/Bookshelf/data/bs.time/loot_tables/time/chest.json

Rename bs.var -> bs.in and bs.res -> bs.out

Add `bs.core:out_to_in/0-[1,2,3,4,5,6,7,8,9]`

This function encapsulate the transfer of output scores in input ones. It allow to reduce the amount of commands to write in a Bookshelf flow

Arctan function doesn't work properly

`bs.health`: Add health:set_by_score

Move score declaration in `_` files

Les fichiers _.mcfunction peuvent servir d’initialisation et peuvent ainsi créer les scores utilisés par le module

-> la partie INIT dans les fichiers ne sera donc plus utile

Add link to other libraries

Liste des datapack d'outil potentiellement intéressant à référencer :

• Oneiric_tools: https://github.com/redcoal27/oneiric_tools
• Delta: https://github.com/BigPapi13/Delta/tree/main
• Iris: https://github.com/Aeldrion/Iris
• Retina: https://github.com/Nico314159/Retina_v2
• TimeLib: https://github.com/BluesCrew/TimeLib
• Callback Scheduler: https://github.com/CloudWolfYT/CW-Callback-Scheduler
• Gui detector: https://github.com/PeerHeer/gui-detector
• Raycast-Raymarch: https://github.com/Neylz/MCF_Raycast-Raymarch
• Ray Collision Detector: https://github.com/K-bai/Minecraft-Ray-Collision-Detector
• mcworld-performance-dp: https://github.com/SnaveSutit/mcworld-performance-dp

N'hésitez pas à me faire part des datapack outil que vous connaissez pour que je les ajoute à la liste ^^

`bs.hitbox`: Advanced hitbox module

• Use the Dispenser API to get the blocs and entity models.
• Convert these models to a set of cubic coordinates [X1,Y1,Z1,X2,Y2,Z2]
  • The union of these cubes must be equal to the initial volume
• Design a function that takes in parameter a position [X,Y,Z] and, optionally, a block ID and look, using a search tee over the blocks/entities, if the coordinate is inside one of the set of cubic coordinates (i.e. inside a block/entity hitbox)
  • If the block ID is not set, then the system will try to call the bs.block:get function
  • If the function is not reachable, then it fallback to a simple detection (if there is a block in the grid cell of the input parameter, it return True, even if the bloc volume doesn't fill all the grid cell volume.
  • The system will also try to detect all the nearby entities and do the same thing (volume -> set of coordinates -> detection of position being inside one of them)

`bs.location`: Fixe spread

Message de A2va: Si jamais je me suis un petit peu trompé en écrivant la fonction spread pour l'accuracy 10-3. A la ligne 61 il faut mettre cette commande (un multiplicateur de 1 passe moins avec cette précision x) ) execute store result score @s Var2 run data get entity @s Pos[1] 1000

Accurate `bs.view:aimed_entity`

Utiliser la hitbox des entités (necessite #50) pour détecter précisément si une entité est visée ou non

ADD `CONTRIBUTING.md`

I propose to add a guideline contribution

basis_rotation_3d is not working properly

From unit tests:

`bs.math`: Rename logarithm functions log -> ln and log10 -> log

Yellow Shulker Convention

Message de RedCoal: d'ailleurs la yellow shulker box pour manip d'inventaire a été mise? je viens de check il y a pour la shulker box normal mais pour respecter les conventions faudrais passer sur la yellow dans minecraft/loot_tables/blocks du coup faudrais replace aussi dans le module de théo la shulker box pour en mettre une yellow c'est juste par convention comme le fait tous les autres datapacker https://discordapp.com/channels/327762717488316416/606609406725193728/725013366778888314

Check modules and update docs

• biome
• bitwise
• block
• color
• example
• health
• id
• link
• location
• math
• move
• orientation
• schedule
• time
• tree
• vector
• view
• xp

Replace `bs.loc.[x,y,z]` scores by `bs.in.[0,1,2]` ones in the `bs.location:add` function

As the input score doesn't correspond to absolute coordinates, it often break the usage flow by having to swapping these bs.loc scores (which are usually absolute coordinates) with the one used as input of this function.

`bs.traveling` Edit in-game traveling sequences

Create a traveling system that allow user to define keyframes and then compute a trajectory to create in-game traveling squences.

The system should work using only the following commands:

• bs.traveling/create
• bs.traveling/edit
• bs.traveling/play
• bs.traveling/rewind

Traveling sequences will be associated to a unique ID which will be given as parameter for the last three commands. Also, the play and rewind command can also take as config parameter the ID of the keyframe and a speed multiplier.

Steps:

• Implement cubic Bezier curve algorithm
• Create menu that allow user to define and edit keyframes
• Implement travel integrator (position only)
• Add rotations
• Allow user to edit speed between 2 keyframes
• Allow user to edit softness of trajectory before or after a keyframe
• Store all the data in NBT storage
• Add rewind travel integrator

`bs.id`: Fix `update_cuid`

Add `metadata.yml` in every modules

This file must contain:

display_name: <name>
description: <short text>
documentation: <link>
thumbnail: <link>
contains:
- [structure_bank]
- [lib]
- [system]
search_trees:
- [path 1]
- [path 2]

Todo:

• global
• biome
• bitwise
• block
• cache
• color
• core
• example
• health
• id
• item
• link
• location
• mapedit
• math
• memory
• move
• orientation
• schedule
• time
• tree
• vector
• view
• xp

`bs.math`: Refactor exp function for better consistency

Objectives (not every of them can be achieved, the goal is to do the best possible):

• Remove the shift of 2 (keep only shifts of 0 or 3 for basic functions
• Increase the precision
• Increase the speed

Add option to define Y coordinate in `bs.location:spread`

By default, the spread function act like the native one: the player will be teleported randomly in a vertical cilinder, on one of the highest blocks.

It can be very usefull to add a way to teleport the player randomly in a shpere by specifying the Y cooredinate of the center of the area.

Add new scoreboard for metadata

Sometimes, getting information about the library in game can be really convenient. I propose to add a new scoreboard bs.metadata. This scoreboard will store information about the library itself. For instance, each installed module will create a new score in this scoreboard where the key is the module name and the value 1. This allows to other modules/systems to detect if right dependencies are available. This scoreboard can also store Bookshelf version if we version the library one day.

Dynamic debug menu

Générer le menu de debug dynamiquement en fonction de la présence ou nom des tags de debug dans les fonctions afin d'éviter d'avoir un menu principalement vide

`bs.mechanic`: Add mecanic module to simplify creative of dynamical mechanic structures

Suggested by @theogiraudet

This module will essentially rely on the bs.link module. It will encapsulate the offsets and hide conversion between axis (on x, y and z) rotation and natural Minecraft rotation (phi and theta)

This function will contain first these two functions:

• bs.mecanic:define_pivot_ata which will link an entity to a point in space instead of linking it to an entity
• bs.mecanic:rotate_[x,y,z] which allow to rotate the structure from the pivot point

`bs.generation`: Add procedural generation module

Create `bs.vector` score swapping

These functions only allow to quickly transfer values from/to vector objectives.

• bs.vector:swap_inputs will perform bs.vector.[x,y,z] <-> bs.in.[0,1,2]
• bs.vector:from_loc will perform bs.loc.[x,y,z] -> bs.vector.[x,y,z]
• bs.vector:from_outputs will perform bs.out.[0,1,2] -> bs.vector.[x,y,z]

Release artifacts

Actuellement, la release ne fait que zip de code bêtement, ce qui n'est pas très intéressant pour la lib.

Il faudrait plutôt avoir N+3 produits téléchargeable :

• Le monde dans sa globalité, soit l'ensemble du code sauf de .gitignore, .github, generatoretdocs`
• Le datapack entier (datapacks/Bookshelf/* zippé directement dans une archive Bookshelf-<release>)
• Le datapack dev entier (datapacks/Bookshelf Dev/* zippé directement dans une archive Bookshelf-Dev<release>)
• Chaque module sous la forme d'un datapack indépendant (avec et sans dépendance). Pour check les dépendances il suffit de lire le tag load de chaque module.

Level god tiers:

• Au moment de créer les modules indépendant, scanner le code afin de détecter les appels à des fichiers hors du module, de façon récursive, et ajouter ces fichiers (avec leur dossiers parents) à l'archive

`bs.math`: Merge all math submodules

Add `bs.vector:scalar_product`

Create a function that perform a scalar product between two vectors stored in bs.vecotr.[x,y,z] and bs.in.[0,1,2]

Formula of a scalar product :

$$ \begin{pmatrix} x1\\ y1\\ z1 \end{pmatrix} . \begin{pmatrix} x2\\ y2\\ z2 \end{pmatrix} = x1 *x2 + y1 * y2 + z1 * z2 $$

Add to this function an option that allow to automatically normalize the vectors first

The normalization can be performed using this function: https://bookshelf.docs.gunivers.net/en/latest/modules/vector.html#normalize

`bs.hitbox` module

Créer un module hitbox contenant notamment:

• get_entity_height: récupère la hauteur d'une entité
• get_entity_width: récupère la largeur d'une entité
• is_in_entity_ata: détermine si la position d'execution est incluse dans la hitbox de l'entité source
• is_in_block_ata: détermine si l'entité source est dans la hitbox du block ciblé par la position d'execution
• in_entities: place un tag sur toutes les entités dont la position de l’exécution se trouve dans sa hitbox

Rename bs.targetId -> bs.id.target

Fully user managed collisions

Currently, collisions are detected via a built-in method which use a specific block tag to ignore blocks and use the entity position as only source of detection collision. It is sufficient for most of use cases which are point-like projectiles colliding on every solide block... but it doesn't really allow to get further

The idea is then to allow the user to dev his own collision detector (in addition to the collision reaction which is already possible)

Add `bs.example:goggly_eyes`

Add goggly eyes to demonstrate the ability to do physics between different reference frames

`bs.move`: Add follow_path function

A function that allow entities to follow the path generated with pathfinding

Add option to manage the spread behavior

By default, the system will teleport the player on the highest block in the defined area.

We can imagine an option that, according to the value, change this behavior such as:

• 0: Default behavior
• 1: Teleport the entity on top of a block, but not always the highest one
• 2: Teleport the entity randomly in the area without considering the blocks

`bs.block`: BlockState edition system

Idée
Supposons :

• id1 = ID du bloc sans tenir compte des BS (les ID se suivent)
• id2 = ID du block en tenant compte du BS (en gros, c'est ce qu'on a actuellement dans la Glib-Core > module 'block', et les ID se suivent également)

Évidemment dans ces conditions, block.id1 =/= block.id2

• qu'on ai un système BS -> NBT
• qu'on ai un système block -> id1
• qu'on ai un système id1 -> id2

A ce moment là si on veut modifier un BS d'un block, on utilise BS -> NBT, on stock le NBT résultant, puis on utilise block -> id1 suivit de id1 -> id2, ce qui nous donne le premier "id2" du bloc en question (parmi toutes les variations de ce-dit bloc).

De là, on fait un id2 -> block en boucle suivit de BS -> NBT et block -> id1 en incrémentant id2 à chaque fois jusqu'à ce que :

• le nouveau NBT soit égale à celui qu'on a stocké au début -> Le système a réussi à éditer le BS
• le block ne corresponde plus à celui désigné par id1 initial -> Le système n'a pas pu editer le BS car la combinaison indiqué par le NBT n'existe pas sur le bloc indiqué par l'id1

Exemple - Mettons qu'on ai un block d'escalier suivant :
cobblestone_stairs[facing=west,half=bottom,shape=straight,waterlogged=false]

On veut changer l'état de son facing pour le mettre sur north
Du coup :

1. On fait BS -> NBT ce qui copie les blockstate dans un NBT qu'on stock quelque part
2. On modifier ce NBT stocké pour appliquer la modification qu'on veut (en l'occurrence, changer facing en north
3. On utilise block -> id1 pour récupérer l'id "simple" du bloc de cobblestone_stairs
4. On utilise id1 -> id2 pour avoir le premier id "complexe" (incluant les blockstate) correspondant au block de cobblestone_stairs
5. On fait un id2 -> block ce qui va placer un block de cobblestone_stairs avec des BS inconnus
6. On fait un block -> id1 pour s'assurer que le bloc placé soit toujours un bloc de cobblestone_stairs (sinon ça sert à rien)
7. On utilise BS -> NBT pour connaitre les BS de ce bloc
8. On compare ces NBT avec ceux qu'on cherche à avoir (ceux qu'on a stocké à l'étape 1 et modifié à l'étape 2)
9. Si l'étape 6 n'a pas posé de problème et que le test de l'étape 8 n'est pas concluant, alors on incrémente id2 et on revient à l'étape 5

Si à la 6 ème étape on a un score id1 différent de celui obtenu à l'étape 3, alors le système s'arrête cr ça signifie qu'il a testé toutes les variatiosn du bloc en question sans jamais tomber sur la combinaison de blockstate voulu.

Si en revance à l'étape 6 on a toujours le même id1 et qu'en plus à l'étape 8 les deux NBT sont identiques, alors on a réussi à éditer le blockstate.

`bs.astro`: Add astronomy module

Put the rotation of an armor stand/other so that it looks/points at the sun/moon

Rename bs.vector[X,Y,Z] -> bs.vector.[x,y,z]

To respect the convention of the lib

log function is not working

The log function gives uncorrect result, the origine of this is unknown yet.
As all the others log function are based on it, they don't work either

Move `safe_kill` from `bs.health` to `bs.core`

Move math:bitwise/ in an independant module

`bs.vector`: Add `get_from_motion` function

Merge vector.classic and vector.local

Most of the functions doesn't depend on the basis of the vectors, so for future development, keeping this distinction is a non-sense.

Thus, getters (get_[...]) that allow to write a vector directly in the desired base will become get_canonical_[...] and get_local_[...]

Also, rename get_by_actual_orientation -> get_from_current_orientation... french people vs english language 😅

`bs.smart_move`: Add smart move module

Décupler les capacités de mouvement des joueurs en leur premettant de faire des glissades (sprint + crouch), grimper au murs, double jump, dash etc...

`bs.math`: Add scale 3 for `sqrt` function

Current bs.math:sqrt function use an algorithm that admit a limit which prevent using it for number scaled by 10^3. A simple way to implement it is to make a simple dichotomic loop.

Move basis_rotation_3d from `bs.math` to `bs.vector`

bs.opt.[0,1,2,...]

Créer des scores d'option qui permettent de passer des arguments optionnels à des fonctions. Si le score est définit, la fonction l'utilisera et réinitialisera le score aussitôt afin que l'option ne se propage pas sur d'autre fonctions.

-> Devrait déprécier le tag bs.override_config