v0.4.5

.github/workflows/dart.yml

@@ -0,0 +1,26 @@
+#give the pipeline a name
+name: Dart CI
+
+#set conditions to trigger on
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+# define what happens when conditions are met
+jobs:
+  build:
+    # use ubuntu's latest OS
+    runs-on: ubuntu-latest
+    # use the google/dart container (this makes `dart` available to use)
+    container:
+      image: google/dart:latest
+
+    # checkout the code, run pub get and finally run tests
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install dependencies
+        run: dart pub get
+      - name: Run tests
+        run: dart run test

CHANGELOG.md

@@ -2,13 +2,13 @@
 
 ## 0.4.5
 
-- added Biome and corresponding Biomes list
+- added new Time object for dealing with ticks, seconds, days and infinite Duration
+- added time extensions to number allowing to write `10.seconds`, `2.ticks`, `2.4.minutes` etc. to generate time objects 
 - added FillBiome Widget
 - added Execute.on, Execute.summon and Heightmap
 - added Damage Widget
 - added Return Widget and Score.setToFunction tranfering the return value to a score
-- added new Time object for dealing with ticks, seconds, days and infinite Duration
-- added time extensions to number allowing to write `10.seconds`, `2.ticks`, `2.4.minutes` etc. to generate time objects 
+- added Biome and corresponding Biomes list
 - added Display Widget for spawing display objects and animate them
 - added Interaction Widget for spawing interaction entities
 - added preview images of all items and blocks in dartdoc
@@ -18,17 +18,20 @@
 - added << Score operator as an additional "set to" operator(same as >>)
 - updated blocks, items, particles and entities to include content from 1.19.4 and 23w12a
 - updated dependencies
+- updated project to Dart 3
 - changed Score >> operator to also accept Widgets and Files
 - changed project version to also accept decimal numbers like 19.4 for `1.19.4` and react accordingly
 - fixed #25 ScoreTimerModule returning incorrect command with negative value
 - fixed Storage.getData not generating namespace properly
 - fixed log messages while using the getCommands API
+- fixed Bossbar.add generating wrong quotation #26
 - moved Builder Widget to basic
 
-Breaking: Execute Dimension, Clone Dimension, Time 
-
-- Effect, Schedule, Title, Repeat, Timer, ScoreTimer use the new Time object instead of an integer for representing time  
+**Breaking**: 
 
+- Effect, Schedule, Title, Repeat, Timer, ScoreTimer use the new Time object instead of an integer for representing time, you can just append a `.ticks` to the old integer: `ticks: 10 => ticks: 10.ticks` 
+- objD now requires Dart 3, please check if you have the newest version of dart and run `dart fix`  
+- Dimension is no longer an Enum. `Execute.dimension` no longer accepts strings, when using a custom dimension use `Dimension(<name>)`
 ## 0.4.4
 
 - added PlayerJoin.rejoin to only detect once joined players

README.md

@@ -10,7 +10,7 @@ No need to remember which parameters commands take, automatic checking of your c
 
 ## Resources
 
-Learning objD is hard. But there are a few things that can accelerate your start.
+objD has many components. But there are a few things that can accelerate your start.
 
 - [Introductory Video](https://youtu.be/0GfuCUNI1pw) showing everything from project structure, editor setup to installation.
 - [Officical Documentation](https://objd.stevertus.com)
@@ -39,6 +39,12 @@ You can then invoke the new command to create your project, follow the instructi
 dart pub global run objd_cli new <project_name>
 ```
 
+Go into the created directory `cd <project_name>` and to install all dependencies run 
+
+```bash
+dart pub get
+```
+
 For further explanations, refer to the [Intro Video](https://youtu.be/0GfuCUNI1pw), where this is presented in depth.
 
 ## Example
@@ -64,6 +70,27 @@ This simple example creates n armor stands(depending on a variable) each with cu
 
 Where in vanilla commands you would have to change multiple commands, this approach is **flexible** and can easily controlled by parameters.
 
+
+## Updating 
+
+When updating to a new version, change the version tag of objD in the `pubspec.yaml` file.
+> *Note:* also make sure the dart version requirements match the version requirements of objD. For 0.4.5 onwards, Dart `3.0.0` is required.
+
+```yaml
+name: <project_name>
+
+environment:
+  sdk: ">=3.0.0 <4.0.0"
+
+dependencies:
+  objd: ^0.4.5
+
+dev_dependencies:
+  build_runner:
+  objd_gen: ^0.0.3
+
+```
+
 ## Contributing & Bugs
 
 New and fresh ideas are always welcome and greatly appreciated. Please create a [pull request](https://github.com/Stevertus/objD/pulls)to organize new additions.

example/files/load.dart

@@ -6,8 +6,6 @@ class LoadFile extends Widget {
 
   @override
   Widget generate(Context context) {
-    return For.of([
-      // put your load widgets here
-    ]);
+    return For.of([]);
   }
 }

lib/src/basic/time.dart

@@ -1,25 +1,84 @@
 const int _TICKSINDAY = 24000;
 const int _TICKSINSECOND = 20;
 
+/// Object that represents time in minecraft. Usually translated into ticks (20ticks = 1 second).
+/// A **more intuitive** way is to use built in getters on the `num` type and operators.
+///
+/// On any number(`int, double, ...`) you can call `.ticks, .seconds, .minutes` and `.days`
+/// ```dart
+/// t = 2400.ticks,
+/// t = 90.seconds,
+/// t = 1.5.minutes,
+/// ```
 class Time {
   final int ticks;
   double get days => ticks / _TICKSINDAY;
   double get seconds => ticks / _TICKSINSECOND;
   final bool isInfinite;
 
+  /// Object that represents time in minecraft. Usually translated into ticks (20ticks = 1 second).
+  ///
+  /// You can directly construct the time from the integer number of ticks:
+  /// ```dart
+  /// var t = Time(2400);
+  /// ```
+  /// A **more intuitive** way is to use built in getters on the `num` type and operators.
+  ///
+  /// On any number(`int, double, ...`) you can call `.ticks, .seconds, .minutes` and `.days`:
+  ///
+  /// ```dart
+  /// t = 2400.ticks,
+  /// t = 90.seconds,
+  /// t = 1.5.minutes,
+  /// ```
+  ///
+  /// Also all common math and comparison operators are available:
+  ///
+  /// ```dart
+  /// t = 1.minutes + 30.seconds
+  /// t += 20.seconds
+  /// if(t > 10.seconds) {
+  /// 	// do something conditional
+  /// }
+  /// ```
+
+// Using this style is highly recommended, as it leads to readable and understandable code.
+  ///
   const Time(this.ticks) : isInfinite = false;
 
+  /// In case of the [Effect](/wrappers/#effect) widget, it might be useful to pass infinite time.
+  /// This can be done with `Time.infinite()`. \
+  /// Otherwise when a finite time is expected, an error is thrown.
   const Time.infinite()
       : isInfinite = true,
         ticks = -1;
 
   const Time.seconds(int seconds)
       : ticks = seconds * _TICKSINSECOND,
         isInfinite = false;
+  const Time.minutes(int minutes)
+      : ticks = minutes * 60 * _TICKSINSECOND,
+        isInfinite = false;
   const Time.days(int days)
       : ticks = days * _TICKSINDAY,
         isInfinite = false;
 
+  /// For a handy interface which does the conversions automatically, use `Time.duration`:
+  /// | Time.duration |                                   |
+  /// | ------------- | --------------------------------- |
+  /// | ticks         | integer number of ticks(optional) |
+  /// | days          | number of ingame days(optional)   |
+  /// | minutes       | number of minutes(optional)       |
+  /// | seconds       | number of seconds(optional)       |
+  ///
+  /// So we can write 1min 30s the following ways(also using fractional timesteps):
+  ///
+  /// ```dart
+  /// t = Time.seconds(90),
+  /// t = Time.duration(minutes: 1.5),
+  /// t = Time.duration(minutes: 1, seconds: 30),
+  /// ```
+
   factory Time.duration({
     int ticks = 0,
     num? days,
@@ -31,12 +90,22 @@ class Time {
                   (seconds ?? 0 + (minutes ?? 0) * 60) * _TICKSINSECOND)
               .toInt());
 
+  /// In commands when Time is used, string are generated dynamically.
+  /// When days can be expressed in `0.5` steps, the suffix `d` is generated.
+  /// When seconds can be expressed in `0.25` steps, the suffix `s` is generated.
+  ///
+  /// So **a word of warning**, even when providing integer ticks, objD can decide to simplify the commands.
+  /// For example `Time(10)` becomes `0.5s`. This behaviour might change in the future, if there are serious concerns.
+  ///
+  /// In case you want to have just the ticks, either use `.ticks` on a Time object or call `toString` with `reduce` set to false: `Time(10).toString(reduce=false) => 10`.
   @override
-  String toString() {
-    if (ticks % (_TICKSINDAY / 2) == 0) {
+  String toString({bool reduce = true}) {
+    if (isInfinite) throw "Called .toString on an infinite time";
+
+    if (reduce && ticks % (_TICKSINDAY / 2) == 0) {
       return '${ticks / _TICKSINDAY}d'.replaceFirst('.0d', 'd');
     }
-    if (ticks % (_TICKSINSECOND / 4) == 0) {
+    if (reduce && ticks % (_TICKSINSECOND / 4) == 0) {
       return '${ticks / _TICKSINSECOND}s'.replaceFirst('.0s', 's');
     }
     return ticks.toString();
@@ -68,7 +137,7 @@ class Time {
   }
 
   /// Divides this Time by the given [quotient] and returns the truncated
-  /// result as a new Duration object.
+  /// result as a new Time object.
   ///
   /// Throws an [UnsupportedError] if [quotient] is `0`.
   Time operator ~/(int quotient) {

lib/src/basic/types/condition.dart

@@ -58,14 +58,14 @@ class Condition {
     _setCond(cond);
   }
 
-  /// checks if the execution is in a matching dimension
+  /// checks if the chunk of the location is loaded:
   Condition.loaded(Location cond) {
     _setCond(cond, loaded: true);
   }
 
   /// checks if the execution is in a matching biome
   Condition.biome(Biome cond) {
-    _setCond(cond, loaded: true);
+    _setCond(cond);
   }
 
   /// checks for a predicate
@@ -225,6 +225,7 @@ class Condition {
     }
   }
 
+  // ignore: library_private_types_in_public_api
   List<List<_ConditionUtil>> getList() {
     var list = <List<_ConditionUtil>>[[]];
     for (var child in _children) {

lib/src/basic/types/item.dart

@@ -286,14 +286,49 @@ class Item {
   }
 }
 
+/// HideFlags method. It translates the human readable boolean values into an int.
+///
+///| HideFlags   | bools                                 |
+///| ----------- | ------------------------------------- |
+///| enchant     | whether to show the enchantments      |
+///| attributes  | whether to show the attributes        |
+///| unbreakable | whether to show the unbreakable tag   |
+///| canDestroy  | whether to show the canDestroy tag    |
+///| canPlaceOn  | whether to show the canPlaceOn tag    |
+///| others      | whether to show other nbt information |
+///| dye      | whether to show Dyed on leather armor |
+///| armorTrims      | whether to show Upgrade on armors |
+///
+///**Example:**
+///
+///```dart
+///var flags = HideFlags(attributes:true, unbreakable: true, others: true); // = 38
+///...
+///Item(Items.apple,hideFlags: flags)
+///```
 int HideFlags({
+  /// whether to show the enchantments
   bool enchantments = false,
+
+  /// whether to show the attributes
   bool attributes = false,
+
+  /// whether to show the unbreakable tag
   bool unbreakable = false,
+
+  ///  whether to show the canDestroy tag
   bool canDestroy = false,
+
+  /// whether to show the canPlaceOn tag
   bool canPlaceOn = false,
+
+  /// whether to show other nbt information
   bool others = false,
+
+  /// whether to show Dyed on leather armor
   bool dye = false,
+
+  /// whether to show Upgrade on armors
   bool armorTrims = false,
 }) {
   var res = 0;

lib/src/basic/types/transformation.dart

@@ -10,16 +10,30 @@ class Transformation {
   /// scaling(1 being the default size)
   final Vec3 scale;
 
-  /// translation
+  /// translation, shifting the display
   final Vec3 translation;
 
+  /// An object describing the scale, rotation and translation
   Transformation({
     this.right_rotation = (0, 0, 0),
     this.left_rotation = (0, 0, 0),
     this.scale = (1, 1, 1),
     this.translation = (0, 0, 0),
   });
 
+  /// scales display entity
+  factory Transformation.scale(double x, double y, double z) =>
+      Transformation(scale: (x, y, z));
+
+  /// shifts display entity
+  factory Transformation.translate(double x, double y, double z) =>
+      Transformation(translation: (x, y, z));
+
+  /// rotates display entity
+  factory Transformation.rotate(double x, double y, double z) =>
+      Transformation(right_rotation: (x, y, z));
+
+  /// scales all axies uniformly
   factory Transformation.scaleAll(double scale) =>
       Transformation(scale: (scale, scale, scale));
 

lib/src/build/context.dart

@@ -49,7 +49,7 @@ class Context {
     this.file = '',
     this.loadFile = 'load',
     this.mainFile = 'main',
-    this.version = 18,
+    this.version = 20,
     this.path = const Path([]),
     Map<Type, dynamic>? traits,
   }) : _heredityTraits = traits ?? {};

lib/src/modules/score_timer.dart

@@ -18,7 +18,7 @@ class ScoreTimerModule extends Module {
   /// | constructor |  |
   /// |--|--|
   /// |String| the name of the Timer and the Scoreboard |
-  /// |ticks| the delay(as time object) between each execution(required) |
+  /// | ticks       | the delay as [Time](/basics/time) between each execution(required)    |
   /// |child| a Widget that is executed after the delay |
   /// |steps| the number that it counts up every time(default = 1) |
   /// |start| a number that is used to reset the timer after the delay(default = 0) |
@@ -30,7 +30,7 @@ class ScoreTimerModule extends Module {
   /// ```dart
   /// ScoreTimerModule(
   ///           'timer1',
-  ///           ticks: 200, // 10sec
+  ///           ticks: 200.ticks, // 10sec
   ///           child: Log('Timer triggered'),
   ///           steps: 1,
   ///           start: 0,