port: Aurora mapmanip library for map templates, and documentation. (#…

…26803)

* refactor: wrap MILLA in general Rust library

* port: Aurora mapmanip library and documentation.

* update CI libs and TGS build rule

* pass filename properly, raise map helper layer

* Update rust/src/mapmanip/core/mod.rs

Co-authored-by: Luc <[email protected]>
Signed-off-by: warriorstar-orion <[email protected]>

* add a bit more documentation

* make doc more para-centric

* these don't need to be images at all

---------

Signed-off-by: warriorstar-orion <[email protected]>
Co-authored-by: Luc <[email protected]>

.github/workflows/build_milla.yml → .github/workflows/build_rust.yml

@@ -1,13 +1,13 @@
-name: Build MILLA
+name: Build Rust library
 on:
   issue_comment:
     types: created
 
 jobs:
-  build-milla:
+  build-rust:
     if: |
       github.event.issue.pull_request &&
-      (github.event.comment.body == '!build_milla') &&
+      (github.event.comment.body == '!build_rust') &&
       ((github.event.sender.id == github.event.issue.user.id) ||
       (github.event.comment.author_association == 'COLLABORATOR') ||
       (github.event.comment.author_association == 'MEMBER') ||
@@ -53,7 +53,7 @@ jobs:
           ref: ${{ env.PR_BRANCH }}
           token: ${{ env.GH_TOKEN }}
 
-      - name: Build MILLA
+      - name: Build rustlibs
         env:
           BASE_BRANCH: ${{ github.event.repository.default_branch }}
           BASE_REPOSITORY: ${{ github.repository }}
@@ -65,7 +65,7 @@ jobs:
           git pull origin "$PR_BRANCH" --depth=$((ahead_by + 1))
           git remote add upstream "https://github.com/$BASE_REPOSITORY.git"
           git fetch upstream "$BASE_BRANCH" --depth=$((behind_by + 1))
-          cd milla
+          cd rust
 
           # Get dependencies.
           rustup target add i686-unknown-linux-gnu
@@ -79,13 +79,13 @@ jobs:
           cargo build --release --target i686-pc-windows-gnu
 
           # Copy the built targets to their checked-in locations.
-          cp target/i686-unknown-linux-gnu/release/libmilla.so ../tools/ci/libmilla_ci.so
-          cp target/i686-pc-windows-gnu/release/milla.dll ../milla.dll
+          cp target/i686-unknown-linux-gnu/release/librustlibs.so ../tools/ci/librustlibs_ci.so
+          cp target/i686-pc-windows-gnu/release/rustlibs.dll ../rustlibs.dll
 
-          git commit -a -m "Build MILLA" --allow-empty
+          git commit -a -m "Build Rust library" --allow-empty
           git push origin
 
       - name: Notify Failure
         if: failure() && env.FAIL_NOTIFIED != 'true'
         run: |
-          gh pr comment ${{ github.event.issue.html_url }} -b 'Building MILLA failed, see the action run log for details: https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}'
+          gh pr comment ${{ github.event.issue.html_url }} -b 'Building Rust library failed, see the action run log for details: https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}'

.gitignore

@@ -73,7 +73,7 @@ $RECYCLE.BIN
 *.swp
 
 # Rust output.
-/milla/target/*
+/rust/target/*
 
 # mkdocs output.
 site

code/__DEFINES/milla.dm → code/__DEFINES/rust.dm

@@ -1,87 +1,93 @@
-// milla.dm - DM API for milla extension library
+// DM API for Rust extension modules
+// Current modules:
+// - MILLA, an asynchronous replacement for BYOND atmos
+// - Mapmanip, a parse-time DMM file reader and modifier
 
-// Default automatic MILLA detection.
+// Default automatic library detection.
 // Look for it in the build location first, then in `.`, then in standard places.
 
-/* This comment bypasses grep checks */ /var/__milla
+/* This comment bypasses grep checks */ /var/__rustlib
 
-/proc/__detect_milla()
+/proc/__detect_rustlib()
 	if(world.system_type == UNIX)
 #ifdef CIBUILDING
-		// CI override, use libmilla_ci.so if possible.
-		if(fexists("./tools/ci/libmilla_ci.so"))
-			return __milla = "tools/ci/libmilla_ci.so"
+		// CI override, use librustlibs_ci.so if possible.
+		if(fexists("./tools/ci/librustlibs_ci.so"))
+			return __rustlib = "tools/ci/librustlibs_ci.so"
 #endif
 		// First check if it's built in the usual place.
-		if(fexists("./milla/target/i686-unknown-linux-gnu/release/libmilla.so"))
-			return __milla = "./milla/target/i686-unknown-linux-gnu/release/libmilla.so"
+		if(fexists("./rust/target/i686-unknown-linux-gnu/release/librustlibs.so"))
+			return __rustlib = "./rust/target/i686-unknown-linux-gnu/release/librustlibs.so"
 		// Then check in the current directory.
-		if(fexists("./libmilla.so"))
-			return __milla = "./libmilla.so"
+		if(fexists("./librustlibs.so"))
+			return __rustlib = "./librustlibs.so"
 		// And elsewhere.
-		return __milla = "libmilla.so"
+		return __rustlib = "librustlibs.so"
 	else
 		// First check if it's built in the usual place.
-		if(fexists("./milla/target/i686-pc-windows-msvc/release/milla.dll"))
-			return __milla = "./milla/target/i686-pc-windows-msvc/release/milla.dll"
+		if(fexists("./rust/target/i686-pc-windows-msvc/release/rustlibs.dll"))
+			return __rustlib = "./rust/target/i686-pc-windows-msvc/release/rustlibs.dll"
 		// Then check in the current directory.
-		if(fexists("./milla.dll"))
-			return __milla = "./milla.dll"
+		if(fexists("./rustlibs.dll"))
+			return __rustlib = "./rustlibs.dll"
 		// And elsewhere.
-		return __milla = "milla.dll"
+		return __rustlib = "rustlibs.dll"
 
-#define MILLA (__milla || __detect_milla())
+#define RUSTLIB (__rustlib || __detect_rustlib())
 
-#define MILLA_CALL(func, args...) call_ext(MILLA, "byond:[#func]_ffi")(args)
+#define RUSTLIB_CALL(func, args...) call_ext(RUSTLIB, "byond:[#func]_ffi")(args)
 
 /proc/milla_init_z(z)
-	return MILLA_CALL(initialize, z)
+	return RUSTLIB_CALL(milla_initialize, z)
 
 /proc/is_milla_synchronous(tick)
-	return MILLA_CALL(is_synchronous, tick)
+	return RUSTLIB_CALL(milla_is_synchronous, tick)
 
 /proc/set_tile_atmos(turf/T, airtight_north, airtight_east, airtight_south, airtight_west, atmos_mode, environment_id, oxygen, carbon_dioxide, nitrogen, toxins, sleeping_agent, agent_b, temperature, innate_heat_capacity)
-	return MILLA_CALL(set_tile, T, airtight_north, airtight_east, airtight_south, airtight_west, atmos_mode, environment_id, oxygen, carbon_dioxide, nitrogen, toxins, sleeping_agent, agent_b, temperature, innate_heat_capacity)
+	return RUSTLIB_CALL(milla_set_tile, T, airtight_north, airtight_east, airtight_south, airtight_west, atmos_mode, environment_id, oxygen, carbon_dioxide, nitrogen, toxins, sleeping_agent, agent_b, temperature, innate_heat_capacity)
 
 /proc/get_tile_atmos(turf/T, list/L)
-	return MILLA_CALL(get_tile, T, L)
+	return RUSTLIB_CALL(milla_get_tile, T, L)
 
 /proc/spawn_milla_tick_thread()
-	return MILLA_CALL(spawn_tick_thread)
+	return RUSTLIB_CALL(milla_spawn_tick_thread)
 
 /proc/get_milla_tick_time()
-	return MILLA_CALL(get_tick_time)
+	return RUSTLIB_CALL(milla_get_tick_time)
 
 /proc/get_interesting_atmos_tiles()
-	return MILLA_CALL(get_interesting_tiles)
+	return RUSTLIB_CALL(milla_get_interesting_tiles)
 
 /proc/reduce_superconductivity(turf/T, list/superconductivity)
 	var/north = superconductivity[1]
 	var/east = superconductivity[2]
 	var/south = superconductivity[3]
 	var/west = superconductivity[4]
 
-	return MILLA_CALL(reduce_superconductivity, T, north, east, south, west)
+	return RUSTLIB_CALL(milla_reduce_superconductivity, T, north, east, south, west)
 
 /proc/reset_superconductivity(turf/T)
-	return MILLA_CALL(reset_superconductivity, T)
+	return RUSTLIB_CALL(milla_reset_superconductivity, T)
 
 /proc/set_tile_airtight(turf/T, list/airtight)
 	var/north = airtight[1]
 	var/east = airtight[2]
 	var/south = airtight[3]
 	var/west = airtight[4]
 
-	return MILLA_CALL(set_tile_airtight, T, north, east, south, west)
+	return RUSTLIB_CALL(milla_set_tile_airtight, T, north, east, south, west)
 
 /proc/get_random_interesting_tile()
-	return MILLA_CALL(get_random_interesting_tile)
+	return RUSTLIB_CALL(milla_get_random_interesting_tile)
 
 /proc/create_environment(oxygen, carbon_dioxide, nitrogen, toxins, sleeping_agent, agent_b, temperature)
-	return MILLA_CALL(create_environment, oxygen, carbon_dioxide, nitrogen, toxins, sleeping_agent, agent_b, temperature)
+	return RUSTLIB_CALL(milla_create_environment, oxygen, carbon_dioxide, nitrogen, toxins, sleeping_agent, agent_b, temperature)
 
-#undef MILLA
-#undef MILLA_CALL
+/proc/mapmanip_read_dmm(mapname)
+	return RUSTLIB_CALL(mapmanip_read_dmm_file, mapname)
+
+#undef RUSTLIB
+#undef RUSTLIB_CALL
 
 // Indexes for Tiles and InterestingTiles
 // Must match the order in milla/src/model.rs

code/game/objects/effects/map_effects/mapmanip.dm

@@ -0,0 +1,26 @@
+/obj/effect/map_effect/marker/mapmanip
+	name = "mapmanip marker"
+	layer = POINT_LAYER
+
+/obj/effect/map_effect/marker/mapmanip/Initialize(mapload)
+	. = ..()
+	qdel(src)
+
+/obj/effect/map_effect/marker/mapmanip/submap/extract
+	name = "mapmanip marker, extract submap"
+	icon = 'icons/effects/map_effects_96x96.dmi'
+	icon_state = "mapmanip_extract"
+	pixel_x = -32
+	pixel_y = -32
+
+/obj/effect/map_effect/marker/mapmanip/submap/insert
+	name = "mapmanip marker, insert submap"
+	icon = 'icons/effects/map_effects_96x96.dmi'
+	icon_state = "mapmanip_insert"
+	pixel_x = -32
+	pixel_y = -32
+
+/obj/effect/map_effect/marker_helper/mapmanip/submap/edge
+	name = "mapmanip helper marker, edge of submap"
+	icon = 'icons/effects/mapping_helpers.dmi'
+	icon_state = "mapmanip_submap_edge"

code/modules/awaymissions/maploader/reader.dm

@@ -35,7 +35,15 @@ GLOBAL_DATUM_INIT(_preloader, /datum/dmm_suite/preloader, new())
 		if(lastchar == "/" || lastchar == "\\")
 			log_debug("Attempted to load map template without filename (Attempted [tfile])")
 			return
-		tfile = wrap_file2text(tfile)
+
+		// use rustlib to read, parse, process, mapmanip etc
+		// this will "crash"/stacktrace on fail
+		tfile = mapmanip_read_dmm(fname)
+		// if rustlib for whatever reason fails and returns null
+		// try to load it the old dm way instead
+		if(!tfile)
+			tfile = wrap_file2text(fname)
+
 		if(!length(tfile))
 			throw EXCEPTION("Map path '[fname]' does not exist!")
 

docs/CONTRIBUTING.md

@@ -133,26 +133,35 @@ Status of your pull request will be communicated via PR labels. This includes:
 All PRs which modify maps are expected to follow all of our
 [mapping requirements](./mapping/requirements.md).
 
-## Modifying MILLA
+## Modifying Rust Code
 
-Our atmos engine, MILLA, is in the `milla/` directory. It's written in Rust for
-performance reasons, which means it's not compiled the same way as the rest of
-the code. If you're on Windows, you get a pre-built copy by default. If you're
-on Linux, you built one already to run the server.
+Some parts of Paradise are written in [Rust][] for performance or reliability
+reasons:
 
-If you make changes to MILLA, you'll want to rebuild. This will be very similar
-to RUSTG: https://github.com/ParadiseSS13/rust-g The only difference is that you
-run `cargo` from the `milla/` directory, and don't need to specify
-`--all-features` (though it doesn't hurt).
+- Our atmos engine, MILLA, is in the `rust/src/milla/` directory.
+- The `mapmanip` library, an Aurora Station module used for automating DMM
+  modification, is in the `rust/src/mapmanip` library.
+
+The Rust parts of our codebase are compiled into a single library,
+separate from the rest of the code. If you're on Windows, you get a pre-built
+copy by default. If you're on Linux, you built one already to run the server.
+
+If you make changes to the Rust library, you'll want to rebuild. This will be
+very similar to [rust-g][]. The only difference is that you run `cargo` from the
+`rust/` directory, and don't need to specify `--all-features` (though it doesn't
+hurt).
 
 The server will automatically detect that you have a local build, and use that
 over the default Windows one.
 
-When you're ready to make a PR, please DO NOT modify `milla.dll` or
-`tools/ci/libmilla_ci.so`. Leave "Allow edits and access to secrets by
-maintainers" enabled, and post a comment on your PR saying `!build_milla`. A bot
+When you're ready to make a PR, please DO NOT modify `rustlibs.dll` or
+`tools/ci/librustlibs_ci.so`. Leave "Allow edits and access to secrets by
+maintainers" enabled, and post a comment on your PR saying `!build_rust`. A bot
 will automatically build them for you and update your branch.
 
+[Rust]: https://www.rust-lang.org/
+[rust-g]: https://github.com/ParadiseSS13/rust-g
+
 ## Other Notes
 
 - Bloated code may be necessary to add a certain feature, which means there has