Allow apps to retrieve information about the source (#1229)

* Give information about the sources

* Document source related system_info properties

docs/scarpet/api/Auxiliary.md

@@ -681,13 +681,13 @@ Fetches the value of a system property or returns all inforation as a map when c
 fetch various information, mostly not changing, or only available via low level
 system calls. In all circumstances, these are only provided as read-only.
 
-Available options in the scarpet app space:
+##### Available options in the scarpet app space:
   * `app_name` - current app name or `null` if its a default app
   * `app_list` - list of all loaded apps excluding default commandline app
   * `app_scope` - scope of the global variables and function. Available options is `player` and `global`
   * `app_player` - returns a player list that have app run under them. For `global` apps, the list is always empty
  
- Relevant world related properties
+##### Relevant world related properties
   * `world_name` - name of the world
   * `world_seed` - a numeric seed of the world
   * `world_dimensions` - a list of dimensions in the world
@@ -702,7 +702,7 @@ Available options in the scarpet app space:
   * `world_center` - Returns coordinates of the center of the world with respect of the world border
   * `world_size` - Returns size of the world where at this distance from `world_center` world border appears.
   * 
- Relevant gameplay related properties
+##### Relevant gameplay related properties
   * `game_difficulty` - current difficulty of the game: `'peaceful'`, `'easy'`, `'normal'`, or `'hard'`
   * `game_hardcore` - boolean whether the game is in hardcore mode
   * `game_storage_format` - format of the world save files, either `'McRegion'` or `'Anvil'`
@@ -719,7 +719,7 @@ Available options in the scarpet app space:
   * `game_data_version` - data version of the game. Returns an integer, so it can be compared.
   * `game_stable` - indicating if its a production release or a snapshot
   
- Server related properties
+##### Server related properties
  * `server_motd` - the motd of the server visible when joining
  * `server_ip` - IP adress of the game hosted
  * `server_whitelisted` - boolean indicating whether the access to the server is only for whitelisted players
@@ -734,7 +734,21 @@ list may refer to the previous tick performance. In this case the last entry (ti
 tick. For all intent and purpose, `system_info('last_tick_times'):0` should be used as last tick execution time, but
 individual tick times may vary greatly, and these need to be taken with the little grain of averaging.
  
- System related properties
+##### Source related properties
+ 
+ The source is what is the cause of the code running, with Carpet using it same way as Minecraft commands use to run. Those are used in
+ some API functions that interact with the game or with commands, and can be manipulated if the execution is caused by an `execute` command, modified
+ by some functions or ran in non-standard ways. This section provides useful information from these cases (like running from a command
+ block, right clicking a sign, etc)
+ * `source_entity` - The entity associated with the execution. This is usually a player (in which case `player()` would get the entity from this),
+                         but it may also be a different entity or `null` if the execution comes from the server console or a command block.
+ * `source_position` - The position associated with the execution. This is usually the position of the entity, but it may have been manipulated or
+                           it could come from a command block (no entity then). If this call comes from the server console, it will be the world spawn.
+ * `source_dimension` - The dimension associated with the execution. Execution from the server console provides `overworld` as the dimension.
+                            This can be manipulated by running code inside `in_dimension()`.
+ * `source_rotation` - The rotation associated with the execution. Usually `[0, 0]` in non-standard situations, the rotation of the entity otherwise.
+ 
+##### System related properties
  * `java_max_memory` - maximum allowed memory accessible by JVM
  * `java_allocated_memory` - currently allocated memory by JVM
  * `java_used_memory` - currently used memory by JVM
@@ -744,7 +758,7 @@ individual tick times may vary greatly, and these need to be taken with the litt
  * `java_system_cpu_load` - current percentage of CPU used by the system
  * `java_process_cpu_load` - current percentage of CPU used by JVM
  
- Scarpet related properties
+##### Scarpet related properties
  * `scarpet_version` - returns the version of the carpet your scarpet comes with.
 
 ## NBT Storage

src/main/java/carpet/script/api/Auxiliary.java

@@ -736,6 +736,7 @@ public class Auxiliary {
             return Value.TRUE;
         });
 
+        // Should this be deprecated for system_info('source_dimension')?
         expression.addContextFunction("current_dimension", 0, (c, t, lv) ->
                 ValueConversions.of( ((CarpetContext)c).s.getWorld()));
 

src/main/java/carpet/script/utils/SystemInfo.java

@@ -5,6 +5,7 @@ import carpet.CarpetSettings;
 import carpet.script.CarpetContext;
 import carpet.script.CarpetScriptHost;
 import carpet.script.value.BooleanValue;
+import carpet.script.value.EntityValue;
 import carpet.script.value.ListValue;
 import carpet.script.value.MapValue;
 import carpet.script.value.NumericValue;
@@ -17,11 +18,9 @@ import com.sun.management.OperatingSystemMXBean;
 import net.fabricmc.loader.api.FabricLoader;
 import net.fabricmc.loader.api.ModContainer;
 import net.minecraft.SharedConstants;
-import net.minecraft.server.world.ServerWorld;
 import net.minecraft.util.WorldSavePath;
-import net.minecraft.util.registry.RegistryKey;
+import net.minecraft.util.math.Vec2f;
 import net.minecraft.world.GameRules;
-import net.minecraft.world.World;
 import net.minecraft.world.WorldProperties;
 import net.minecraft.world.border.WorldBorder;
 
@@ -199,6 +198,15 @@ public class SystemInfo {
             });
             return MapValue.wrap(rules);
         });
+
+        put("source_entity", c -> EntityValue.of(c.s.getEntity()));
+        put("source_position", c -> ValueConversions.of(c.s.getPosition()));
+        put("source_dimension", c -> ValueConversions.of(c.s.getWorld()));
+        put("source_rotation", c -> {
+            Vec2f rotation = c.s.getRotation();
+            return ListValue.of(new NumericValue(rotation.x), new NumericValue(rotation.y));
+        });
+        
         put("scarpet_version", c -> StringValue.of(CarpetSettings.carpetVersion));
 
     }};