Scarpet

What is scarpet

"Scarpet is a fully featured, in-game, programming language that you can use to code new tools and new behaviours, and all of it's in-game, preserving the vanilla feel. Ummm, so it works little bit like datapacks. So if you have an itch to, maybe do some, err programming in minecraft, or you haven't programmed, and you just want to learn how to code, in your favourite game, that might be a good place to start" - gnembon

How to get scarpet

Scarpet comes built into the carpet mod. Check the releases page of this repo for the most recent version, and the changelog at the bottom to see what's new

How to use scarpet apps

You can go to this page and get all the apps you want Then go to world saves file, and create a new folder called scripts and in it put all your .sc files Then open the game and type in command /script load scriptname Then the script will run. Some apps require you to add global at the end, in which case it will tell you (usually in the form of an error message) and then you just do /script load scriptname global

(All programs are available as is. They might be incorrect, they might be outdated. If you see some problems, either open a pull request with a fix or report on the bug tracker for someone else to look into it)

How to write new scarpet apps

Open a new file in your scripts folder caled scriptname.sc and then write whatever code you want, and then run it to see if it works. Pro tip: Do this in a specific world, away from anything delicate. Test your scripts there THEN take them over to your actual world where you may wish to use them.

Help! I wanna scarpet but IDK how!

That's ok, cos there are some docs here which explain it all. It just takes some practice and dedication, and you'll get there in the end. Perseverance is the defining factor of a winner. (I feel like Socrates now)

How to make it easier?

Scarpet currently has support for the following editors:

• Notepad++ (by gnembon): Get the most current version

• IntellijIDEA (by gnembon): Read the document

• VScode (by Uriel/ImUrX): Get the latest version and install it into VSCode using instructions on Readme if you don't know how

• Atom (by replaceitem): Installation instructions are in Readme

Documentation and Examples

Scarpet API docs

Changelog

v1.7

• changed and expanded available entity descriptors for entity_list and entity_area, Now they support all entity types and categorizations. Previous
• descriptors that were not consistent, like 'players' or 'items' are removed.
• improved precision of entity targetting with entity_area.
• added label to supported shapes as floating text
• allow for discrete snapping of client shapes, using 'dxdydz' as opposite to 'xyz'
• type of 'task' is reported properly
• expanded entity API with 'path', 'brain', 'active_block', and 'breaking_progress' functions
• solved hash collisions for shapes caused by vanilla vec3d(-8,8,-8) == vec3d(8,8,8)
• added __on_player_swaps_hands event handles
• fixed issue where command-defined events were preventing apps events from registering
• attached entity events (via entity_event) will execute with the context (dimension, position, etc) of the entity
• events of taking damage, block breaking, and using item are called a bit earlier - before they have an effect in vanilla
• fixed nbt values reporting their initial value despite being modified
• events of updating hotbar slot and craft request will trigger only once
• addition on maps treats them like sets and produces merged maps. Lists operations are still propritizing vector approach, not lists approach.
• new structure and plop (world gen) API for 1.16.2 (incoming) support for features and structures in json. Your previous names used with structure API and especially plop will not work but going forwards, names will be compatible with Mojang datapack specs.
• documented how to setup scarpet markers as armorstand type markers
• Officially supported new map and list constructor syntax. You have 1.4.0 and are missing {} and [] - don't worry - it works in 1.4 as well, it is just not documented. Previous functional notation (using m() and l() ) is fully supported and the 'proper' way to do it.
• -> operator in map constructor context now returns a tuple of its arguments. To construct a set of functions, you would have to add them one by one now, as -> will be creating pairs, not defining functions Previously:

__config() -> m( l('stay_loaded', true) );
global_precious_blocks = l('dirt', 'stone');

Now, this would also work:

__config() -> { 'stay_loaded' -> true };
global_precious_blocks = ['dirt', 'stone'];

• fixed lighting issues when resetting chunks with reset_chunk. Now it all resets properly. Thanks to PhiPro
• added persistence (query and modify) to the entity API
• without_updates and in_dimension should now be thread safe
• support for threaded execution via task, task_value, task_join, task_count, task_completed, synchronize and task_dock.
• added import support - allows to modularize your apps and use libraries (extension .scl)
• structure API to query and modify game structures via structures, structure_set, structure_eligibility
• POI API to access and make changes to the POI system via poi and set_poi
• global system variables for better interapperability via system_variable_get and system_variable_set
• noise generation via perlin and simplex
• scoreboard API via scoreboard, scoreboard_add, scoreboard_remove, scoreboard_display
• client facing shapes drawing via draw_shape
• ability for scripts to read, load and write to files of with NBT and plain text. Better organization of scripts files
• API for handling stats via statistics and event __on_statistic
• added game event handlers
• __on_player_interacts_with_block
• __on_player_places_block
• __on_chunk_generated
• __on_lightning
• __on_player_takes_damage
• __on_player_deals_damage
• __on_player_dies
• __on_player_respawns
• __on_player_connects
• __on_player_disconects
• __on_player_chooses_recipe
• __on_player_switches_slot
• added __on_close
• events with global scope (like __on_tick) can only be triggered for apps with global scope.
• expanded entity api: permission_level, effect, breeding_age, pose, display_name, command_name, team, gamemode, jumping, jump, silent, gravity, fire, hunger, saturation, exhaustion, add_exhaustion, nbt, nbt_merge
• added stack traces to error messages
• player enderchest access
• support for '\n' and '\t' characters in strings
• added seed, in_slime_chunk, reset_chunk, without_updates, c_for, is_chunk_generated, world_time, day_time, inhabited_time, last_tick_times, spawn_potential, portal_cooldown, portal_timer, add_chunk_ticket, reload_chunk, view_distance, mob_counts, unix_time, convert_date, parse_nbt, encode_nbt, recipe_data
• better support for break and continue in functions like scan and volume
• added support for all new nether blocks, materials, sounds, etc
• set_biome is now y value sensitive. Use 0 in the end and overworld, and actual Y value for the nether
• lots of bugfixes...

v1.6

• allowed for much smaller transparencies for scarpet client-facing shapes
• allowed for /-+_/ characters in file names for app accessed files
• improved performance in handling ops in NBT tags
• added more options to handle block properties and block data support for set
• added parse_nbt and encode_nbt as ways to convert scarpet values from and to nbt tags
• added nbt and nbt_merge to entity modify API
• added unix_time() and convert_date() for date / time manipulations
• added support for block position arguments and triples for scan, volume, rect and diamond
• added hooks for __on_player_chooses_recipe and __on_player_switches_slot events
• added recipe_data() and crafting_remaining_item() - for convenient and easy crafting scripts
• added optional player argument to print. when called print(player, msg) it will only display this message to that player.
• added cylinder shape to scarpet shapes
• ability of sending shapes via draw_shape in bulk to minimize network packets
• duration of shapes can be set to 0 - this turns them off immediately
• added ability for shapes to snap to various combinations of coordinates, not only to all of them
• switched to 64bit FNV-1a algorithm for keying of shapes to minimize collisions
• optimized rendering of shapes that do not render all faces/lines
• shapes that 'follow' entities now move smoothly with high framerates, not just 20/s
• inventories for players can be specified as strings (player names) as well as 'enderchest_' to denote their enderchest content
• added hunger, saturation, exhaustion and add_exhaustion to (player) entity API
• added read_file, delete_file, and write_file as preferred functions to access external files. use of load_app_data and - - store_app_data on external files is now deprecated (still supported) and its use is limited to the system managed app tag.
• added the ability to handle textual files, apart from nbt files.
• added mob_counts() (1.16 +) to query mob cap information in scripts
• added 'cylinder' shape to scarpet shapes
• ability of sending shapes via draw_shape in bulk to minimize network packets
• duration of shapes can be set to 0 - this turns them off immediately
• added ability for shapes to snap to various combinations of coordinates, not only to all of them
• switched to 64bit FNV-1a algorithm for keying of shapes to minimize collisions
• optimized rendering of shapes that do not render all faces/lines
• shapes that follow entities now move smoothly with high framerates, not just 20/s
• inventories for players can be specified as strings (player names) as well as 'enderchest_' to denote their enderchest content
• added hunger, saturation, exhaustion and add_exhaustion to (player) entity API
• added read_file, delete_file, and write_file as preferred functions to access external files. use of load_app_data and store_app_data on external files is now deprecated (still supported) and its use is limited to the system managed app tag.
• added the ability to handle textual files, apart from nbt files.
• added __on_player_connects and __on_player_disconnects events
• added view_distance() as reported by the game
• events now cannot be registered and handled in libraries and imports. each app has to define its callbacks directly in the app main file to handle those.
• added draw_shape allowing rendering of custom shapes to clients. Vanilla clients connected to carpet servers will receive replacement rendering based on dust particles. Drawn shapes can be static, or follow entities. GitHub
• cleaner log when placing structures and features
• added reload_chunk to resend chunk data to the clients, and added option to set_biome not to update chunk data with the clients
• added add_chunk_ticket to temporarily load remote chunks. Only natural chunk tickets are supported at the moment results of poi come out sorted by center distance as of now.
• added portal_cooldown and portal_timer to entity API query and modify
• better handling of errors in docked section of threaded tasks to merge stack traces all the way to the top of the thread
• renamed 'vine' material to 'vegetation' and 'redstone_bits' to 'decoration'
• arguments for schedule and task will be evaluated at the time of call, so things like loop(10, task( _(outer(_))->print(_))) now pass arguments as you would expect them to do.
• added task_dock to allow tasks to run a block of code in a server-synchronized fashion
• fixed multiple typos in scarpet docs (thanks to James103)
• fixed double evaluation in spawn function
• place_item can now handle non-block items, like bonemeal, flint and steel, or axes
• added spawn_potential
• added structure_eligibility that works like structures, but return structure information based on seed, not the structures actually placed in the world
• fixed multiline strings in apps causing error lines in error reports and stack traces to be offset.
• scoreboard_remove(objective, player) will now remove score for a given key
• added format() function to allow for text formatting, including custom RBG colors for 1.16
• added gamemode(which accepts strings, case insensitive, or numbers 0-3), jumping which makes you jump continuously, and jump to make you jump once, silent and gravity with boolean modifiers and fire with no. of fire ticks (0 for extinguishing) to modify
• added query(e, 'category') to get mob category: monster, creature, ambient, water_creature, misc and water_ambient in 1.16+
• scarpet programs loaded via world scripts folders are now referred to as scarpet apps.
• functions are now proper function values, and are closures thanks to the redefined outer call, so they can hold state. Good alternative to global values.
• added anonymous functions via _(args) -> body
• scripts now ignore redundant and unnecessary extra semicolons - feel free to spam them at the end of expressions, even if not needed.
• added call to call functions directly (by name or lambda reference)
• added copy for deep copy of nested values. With that - all values are now passed by reference in function arguments
• added loaded_status(), generation_status() and chunk_tickets() to debug loading issues using scarpet.
• calling block() directly on a block value, like in scan() will cause to resolve it. Otherwise block values are lazy until they are needed.
• apps can now bind to the events on the fly, no need to have callbacks defined only on the first code pass
• entity events are now separated between apps. There can be multiple apps running the same entity at the same time, not knowing about each other.
• loops and higher order functions now will not accept the exit block, since continue() and break() functions were introduced to use in loops and higher order functions.
• restored plop function for 1.15
• scarpet markers are cleaned automatically if an app is not loaded.
• added replace(str, regex, repl), replace_first(str, regex, repl), escape_nbt
• added new entity options, ai and no_clip

v1.5

• added ability for apps to keep their persistent state using load_app_data and store_app_data functions
• added maps via m() function
• added proper nbt support via nbt() function
• all containers (lists, maps and nbts) now have unified api via get, has, put and delete functions
• added L-value behaviour to certain functions and operators, like get, has, put, delete, =, +=
• new : operator - highest priority - to access containers elements, alias for get function
• changed priority of ~ match operator to match :
• numbers have to start because of that with a number, so .123 won't float anymore, use 0.123 instead
• added in_dimension(dimension, expr) to change the execution context for the subexpression, for instance to place blocks in the nether while running a script in the overworld
• added carpet mod setting /carpet scriptsAutoload to automatically load scarpet packages from disk on server / game start which works even with /script command fully disabled. However, scipts to stay loaded need to return proper app config by defining __config() function. See /script load section for details.
• added entity_event to add functions to be called when certain events happen for an entity
• added four more general use events: player_releases_item (bows, aborting actions, controlled client side), player_finishes_using_item (item consumed, eating etc. server controlled), player_drops_item for single item dropped, and player_drops_stack for dropping entire stack.

v1.4

• top to get the top block at position now requires full block coordinates, but Y value is ignored.
• Inventories of blocks and entities got their API as well. Check stack_limit, inventory_size, inventory_get, inventory_set, inventory_find, inventory_remove and drop_item functions.
• scripts loaded from disk (via /script load/unload command) will operate in each player space by default, unless loaded with shared option.
• the newline markers for 'in-commandblock' type scripts are now fully parsed, meaning you can have $ in strings. $ markers are supported only with in-game cases.
• support for comments via // in scripts loaded from world files. Comments are only allowed in external file scripts.
• tab completion for typing programs in commands manually (in /script command)
• unloading/reloading a module removes all event callbacks from that module
• return, throw, exit, as well as the 'catch' expression of try can be omitted, assuming null
• if with no else expression will 'else' to null
• element(list,index) has been deprecated, and replaced with get(value,address), working on lists as well as nbt constructs
• there is a new nbt type, that behave like string, but can be queried with get more efficiently
• primitive types of nbt are now converted to primitive scarpet types when queried. This doesn't apply to compound nbts
• iterators, like range, rect, can be reused and moved about in a variable.
• added type function to recognized held variable type.
• str format arguments can now be passed in a single list
• block values now properly handle block entity data, meaning set-ting a chest from another location will retain its content.
• therefore set can also accept custom BE tag?
• place_item to replicate the action of a player placing a block of item
• set_biome to sets permanently a custom biome at a position. For those missing a custom command to do that in carpet, just use /script scan 0 0 0 x1 0 z1 x2 0 z2 set_biome(_,'swamp') for the same effect
• block_properties lists all available block properties at position
• block_data returns nbt of a block at position
• property makes sure all value comes out lowercased.
• spawn function to spawn entities like /summon command but retaining access to them.
• entity ~ 'look' will return a look vector of an entity. No need to math yaw pitch here.
• entity ~ 'selected_slot' to return current selected slot for players
• entity ~ 'facing' returns a facing order of a player
• entity ~ 'trace' ca be used to ray trace blocks, liquids and entities
• entity ~ sugar can now support
• fixed modify(e,'custom_name',null) to actually clear custom name
• create_marker and remove_all_markers for easy marking I guess
• fixed 'double evaluation' caused by print function
• setting various entities motions and positions should update properly to the clients
• fixed thoughts too dope when trying to compare list to a number

v1.3

• Added 1.14 specific structures to plop for 1.14 (fabric-carpet)
• added destroy and harvest functions for other valid methods of breaking blocks
• added schedule to delay execution of user defined functions for later ticks
• scarpet now allows to intercept most important user actions related events. Check utilities\event_test.sc and load via /script load event_test to test event handling.

v1.2

• fixes to lists handling
• fixed issue with running 'run' command in functions
• scripts can now be loaded from files in /scripts/ folder inside world directory. These also can be edited normally, without extra $ to indicate new lines.
• each file represents a package and is run independently from others.
• /script load/unload
• /script in run/invoke etc...
• script modules loaded from scripts / bundled with carpetmod can make new commands. details - later.

v1.1

• put function to modify lists content
• _ in loop functions can be used to change content of sublists
• minor performance improvements
• scripting engine will reset with world loading
• typos with gragon eggs
• player movement is much smoother when controlled with modify function
• loaded and loaded_ep won't load the points, lol
• if executed as /execute as @p script run... print will output to players chat, not system log
• no need to disable commandBlockOutput - scripts will no longer output results of intermediate results.

v1.0

• everything