Minecraft: Java Edition 26.3 rewritten from scratch in Rust, checked against vanilla with 281 differential harnesses. Get it with the Horizon launcher.
Rust differential-testinggame-enginegamedevlinuxminecraftminecraft-javareimplementationrustvoxelvulkanwgpu
//! Generate the typed mod interface from native hook signatures and catalog contracts.
use quote::ToTokens;
use std::{collections::HashSet, fs, path::Path, process::Command};
use syn::{FnArg, ImplItem, Item, Pat, Type, visit::Visit, visit_mut::VisitMut};
fn impl_functions(item: syn::ItemImpl) -> impl Iterator<Item = syn::ItemFn> {
item.items.into_iter().filter_map(|item| match item {
ImplItem::Fn(method) => Some(syn::ItemFn {
attrs: method.attrs,
vis: method.vis,
sig: method.sig,
block: Box::new(method.block),
}),
_ => None,
})
}
/// The inherent `Game` methods of the files under `path`, each with its module (`native_hooks`,
/// `lan::guest`…) below `module`.
fn game_methods(
path: &Path,
module: &str,
methods: &mut Vec<(String, syn::ItemFn)>,
) -> Result<(), String> {
for entry in fs::read_dir(path).map_err(|e| e.to_string())? {
let path = entry.map_err(|e| e.to_string())?.path();
let stem = path
.file_stem()
.and_then(|s| s.to_str())
.unwrap_or_default();
let inner = format!("{module}::{stem}");
if path.is_dir() {
game_methods(&path, &inner, methods)?;
} else if path.extension().is_some_and(|ext| ext == "rs") {
let source = fs::read_to_string(&path).map_err(|e| e.to_string())?;
let file = syn::parse_file(&source).map_err(|e| format!("{}: {e}", path.display()))?;
for item in file.items {
if let Item::Impl(item) = item
&& item.trait_.is_none()
&& let Type::Path(ty) = &*item.self_ty
&& ty.path.segments.len() == 1
&& ty.path.segments[0].ident == "Game"
{
methods.extend(impl_functions(item).map(|method| (inner.clone(), method)));
}
}
}
}
Ok(())
}
fn doc_comments(
attrs: &[syn::Attribute],
name: &str,
preserve_empty: bool,
) -> Result<String, String> {
let mut docs = String::new();
for attr in attrs.iter().filter(|attr| attr.path().is_ident("doc")) {
let syn::Meta::NameValue(value) = &attr.meta else {
return Err(format!("unsupported doc attribute in {name}"));
};
let syn::Expr::Lit(syn::ExprLit {
lit: syn::Lit::Str(doc),
..
}) = &value.value
else {
return Err(format!("unsupported doc attribute in {name}"));
};
let value = doc.value();
for line in value.split('\n') {
if preserve_empty || !line.is_empty() {
docs.push_str(&format!("///{line}\n"));
}
}
}
Ok(docs)
}
fn exported_types(source: &str, generated: &str) -> Result<HashSet<String>, String> {
fn use_names(tree: &syn::UseTree, names: &mut HashSet<String>) {
match tree {
syn::UseTree::Path(path) => use_names(&path.tree, names),
syn::UseTree::Name(name) => {
names.insert(name.ident.to_string());
}
syn::UseTree::Rename(rename) => {
names.insert(rename.rename.to_string());
}
syn::UseTree::Group(group) => {
for item in &group.items {
use_names(item, names);
}
}
syn::UseTree::Glob(_) => {}
}
}
let mut names = HashSet::new();
for source in [source, generated] {
let file = syn::parse_file(source).map_err(|e| e.to_string())?;
for item in file.items {
let ident = match item {
Item::Use(item) if matches!(item.vis, syn::Visibility::Public(_)) => {
use_names(&item.tree, &mut names);
None
}
Item::Struct(item) if matches!(item.vis, syn::Visibility::Public(_)) => {
Some(item.ident)
}
Item::Enum(item) if matches!(item.vis, syn::Visibility::Public(_)) => {
Some(item.ident)
}
Item::Union(item) if matches!(item.vis, syn::Visibility::Public(_)) => {
Some(item.ident)
}
Item::Type(item) if matches!(item.vis, syn::Visibility::Public(_)) => {
Some(item.ident)
}
Item::Trait(item) if matches!(item.vis, syn::Visibility::Public(_)) => {
Some(item.ident)
}
Item::Mod(item) if matches!(item.vis, syn::Visibility::Public(_)) => {
Some(item.ident)
}
_ => None,
};
if let Some(ident) = ident {
names.insert(ident.to_string());
}
}
}
Ok(names)
}
fn host_method(
method: &syn::ItemFn,
name: &str,
exports: &HashSet<String>,
) -> Result<(String, String), String> {
struct Types<'a> {
exports: &'a HashSet<String>,
error: Option<String>,
}
impl Types<'_> {
fn check_path(&mut self, path: &syn::Path) {
let first = path.segments.first().unwrap().ident.to_string();
let unqualified = path.leading_colon.is_none() && path.segments.len() == 1;
let prelude = unqualified
&& matches!(
first.as_str(),
"bool"
| "char"
| "str"
| "u8"
| "u16"
| "u32"
| "u64"
| "u128"
| "usize"
| "i8"
| "i16"
| "i32"
| "i64"
| "i128"
| "isize"
| "f32"
| "f64"
| "String"
| "Option"
| "Result"
| "Vec"
| "Box"
| "Arc"
| "PathBuf"
| "AsRef"
| "AsMut"
| "From"
| "Into"
| "TryFrom"
| "TryInto"
| "Iterator"
| "IntoIterator"
| "DoubleEndedIterator"
| "ExactSizeIterator"
| "Extend"
| "Fn"
| "FnMut"
| "FnOnce"
| "Sized"
| "Send"
| "Sync"
| "Unpin"
| "Drop"
| "Default"
| "Clone"
| "Copy"
| "PartialEq"
| "PartialOrd"
| "Eq"
| "Ord"
| "ToOwned"
| "ToString"
| "Future"
| "IntoFuture"
);
if path.leading_colon.is_some() || !(prelude || self.exports.contains(&first)) {
self.error = Some(format!(
"type {} is not available in mod_api",
path.to_token_stream()
));
}
}
}
impl<'ast> Visit<'ast> for Types<'_> {
fn visit_type_impl_trait(&mut self, _: &'ast syn::TypeImplTrait) {
self.error = Some("impl Trait is not object-safe".into());
}
fn visit_type_path(&mut self, ty: &'ast syn::TypePath) {
if ty.qself.is_some() {
self.error = Some("qualified associated types are not supported".into());
} else {
self.check_path(&ty.path);
}
syn::visit::visit_type_path(self, ty);
}
fn visit_trait_bound(&mut self, bound: &'ast syn::TraitBound) {
self.check_path(&bound.path);
syn::visit::visit_trait_bound(self, bound);
}
}
if method.sig.asyncness.is_some() {
return Err(format!("{name}: async methods are not object-safe"));
}
if method
.sig
.generics
.params
.iter()
.any(|param| !matches!(param, syn::GenericParam::Lifetime(_)))
{
return Err(format!("{name}: generic methods are not object-safe"));
}
let mut types = Types {
exports,
error: None,
};
for arg in &method.sig.inputs {
if let FnArg::Typed(arg) = arg {
types.visit_type(&arg.ty);
}
}
if let syn::ReturnType::Type(_, ty) = &method.sig.output {
types.visit_type(ty);
}
if let Some(reason) = types.error {
return Err(format!("{name}: {reason}"));
}
let mut sig = method.sig.clone();
let original = sig.ident.clone();
sig.ident = syn::parse_str(name).map_err(|e| format!("invalid helper name {name}: {e}"))?;
let mut args = Vec::new();
if !matches!(sig.inputs.first(), Some(FnArg::Receiver(r)) if r.reference.is_some()) {
return Err(format!("{name}: expected a borrowed Game receiver"));
}
for arg in sig.inputs.iter_mut().skip(1) {
let FnArg::Typed(arg) = arg else {
return Err(format!("{name}: unexpected receiver"));
};
let Pat::Ident(pat) = &mut *arg.pat else {
return Err(format!("{name}: unsupported argument"));
};
pat.mutability = None;
args.push(pat.ident.to_string());
}
let docs = doc_comments(&method.attrs, name, true)?;
Ok((
format!("{docs}{};\n", sig.to_token_stream()),
format!(
"{} {{ self.{original}({}) }}\n",
sig.to_token_stream(),
args.join(", ")
),
))
}
fn has_call(block: &syn::Block, expected: &str) -> bool {
struct Calls<'a> {
expected: &'a str,
found: bool,
}
impl<'ast> Visit<'ast> for Calls<'_> {
fn visit_expr_call(&mut self, call: &'ast syn::ExprCall) {
if let syn::Expr::Path(path) = &*call.func
&& path
.path
.segments
.last()
.is_some_and(|s| s.ident == self.expected)
{
self.found = true;
}
syn::visit::visit_expr_call(self, call);
}
}
let mut calls = Calls {
expected,
found: false,
};
calls.visit_block(block);
calls.found
}
fn one_function<'a>(
items: impl Iterator<Item = &'a syn::ItemFn>,
name: &str,
) -> Result<&'a syn::ItemFn, String> {
let mut matches = items.filter(|item| item.sig.ident == name);
let first = matches
.next()
.ok_or_else(|| format!("expected one {name} signature"))?;
if matches.next().is_some() {
return Err(format!("expected one {name} signature"));
}
Ok(first)
}
fn fresh_name(base: &str, used: &mut HashSet<String>) -> String {
let mut name = base.to_owned();
while !used.insert(name.clone()) {
name.push('_');
}
name
}
/// Turns a hook argument's type into its event field's. A `&mut` primitive scalar becomes the value
/// itself, written back after every mod has run; any other `&mut` stays a reference to the caller's
/// value. Either way one event goes through every mod, so each sees the changes before it. Every
/// elided reference lifetime becomes the event's `'a`, or `'b` inside a `&mut`, which can't shorten
/// it. The launcher keeps a copy for trait injections (`launcher/src/native_mods/inject.rs`); both
/// test the same types.
#[derive(Default)]
struct EventLifetimes {
a: bool,
b: bool,
in_mut: bool,
}
impl EventLifetimes {
/// The field's type, and whether it is a scalar copied in and written back.
fn field(&mut self, ty: &Type) -> (Type, bool) {
let scalar = match ty {
Type::Reference(reference) if reference.mutability.is_some() => {
match &*reference.elem {
Type::Path(path)
if path.qself.is_none()
&& path.path.get_ident().is_some_and(|ident| {
[
"bool", "char", "i8", "i16", "i32", "i64", "i128", "isize",
"u8", "u16", "u32", "u64", "u128", "usize", "f32", "f64",
]
.iter()
.any(|scalar| ident == scalar)
}) =>
{
Some(&*reference.elem)
}
_ => None,
}
}
_ => None,
};
if let Some(scalar) = scalar {
return (scalar.clone(), true);
}
let mut field = ty.clone();
self.visit_type_mut(&mut field);
(field, false)
}
}
impl VisitMut for EventLifetimes {
fn visit_type_reference_mut(&mut self, reference: &mut syn::TypeReference) {
if reference.lifetime.is_none() {
reference.lifetime = Some(syn::parse_quote!('_));
}
let outer = self.in_mut;
self.visit_lifetime_mut(reference.lifetime.as_mut().unwrap());
self.in_mut |= reference.mutability.is_some();
self.visit_type_mut(&mut reference.elem);
self.in_mut = outer;
}
fn visit_lifetime_mut(&mut self, lifetime: &mut syn::Lifetime) {
if lifetime.ident == "_" {
*lifetime = if self.in_mut {
self.b = true;
syn::parse_quote!('b)
} else {
self.a = true;
syn::parse_quote!('a)
};
}
}
}
fn host_for(is_level: bool, mutable: Option<bool>, ticks: bool) -> Option<(&'static str, String)> {
mutable.map(|mutable| {
let (name, kind) = if is_level {
(
"level",
match (mutable, ticks) {
(true, true) => "LevelWriteHost",
(false, true) => "LevelTicksHost",
(true, false) => "LevelRandomHost",
(false, false) => "LevelHost",
},
)
} else {
("host", "Host")
};
let mutable = if mutable || (is_level && ticks) {
"mut "
} else {
""
};
(name, format!("&{mutable}dyn {kind}"))
})
}
pub fn run(check: bool) -> Result<(), String> {
let root = Path::new(env!("CARGO_MANIFEST_DIR")).join("..");
let catalog: serde_json::Value = serde_json::from_str(
&fs::read_to_string(root.join("native-hooks.json")).map_err(|e| e.to_string())?,
)
.map_err(|e| e.to_string())?;
let source = fs::read_to_string(root.join("crates/horizon-client/src/game/native_hooks.rs"))
.map_err(|e| e.to_string())?;
let file = syn::parse_file(&source).map_err(|e| e.to_string())?;
let mut methods = Vec::new();
for item in file.items {
if let Item::Impl(item) = item {
methods.extend(impl_functions(item));
}
}
let mut traits = String::new();
let mut dispatch = String::new();
let mut render_traits = String::new();
let mut render_dispatch = String::new();
let mut seen = HashSet::new();
for hook in catalog["hooks"]
.as_array()
.ok_or("catalog hooks must be an array")?
{
let Some(api) = hook.get("mod_api") else {
continue;
};
let name = hook["name"].as_str().ok_or("hook name missing")?;
if !seen.insert(name.to_owned()) {
return Err(format!("duplicate hook {name}"));
}
let native = format!("native_{name}");
let target = hook["target"].as_str().ok_or("target missing")?;
let is_render = target.starts_with("horizon_client_render::");
let external = target
.strip_prefix("horizon_world::")
.map(|p| ("horizon-world", p))
.or_else(|| {
target
.strip_prefix("horizon_client_render::")
.map(|p| ("horizon-client-render", p))
});
let (method, call) = if let Some((krate, path)) = external {
let Some((module, function)) = path.rsplit_once("::") else {
return Err(format!("wrong target for {name}"));
};
if function != native {
return Err(format!("wrong target for {name}"));
}
let path = root
.join("crates")
.join(krate)
.join("src")
.join(format!("{}.rs", module.replace("::", "/")));
let source =
fs::read_to_string(&path).map_err(|e| format!("{}: {e}", path.display()))?;
let file = syn::parse_file(&source).map_err(|e| e.to_string())?;
let functions: Vec<_> = file
.items
.into_iter()
.filter_map(|item| match item {
Item::Fn(function) => Some(function),
_ => None,
})
.collect();
(
one_function(functions.iter(), &native)?.clone(),
if is_render {
format!("dispatch_{name}")
} else {
name.to_owned()
},
)
} else {
if !target.starts_with("horizon_client::game::native_hooks::")
|| !target.ends_with(&format!("::{native}"))
{
return Err(format!("wrong target for {name}"));
}
(
one_function(methods.iter(), &native)?.clone(),
format!("dispatch_{name}"),
)
};
if !has_call(&method.block, &call) {
return Err(format!("missing {call} call in {native}"));
}
let sig = &method.sig;
let mut args = Vec::new();
let mut receiver_mut = None;
for arg in &sig.inputs {
match arg {
FnArg::Receiver(r) => {
receiver_mut = Some(r.mutability.is_some());
}
FnArg::Typed(arg) => {
let Pat::Ident(pat) = &*arg.pat else {
return Err(format!("unsupported argument in {name}"));
};
args.push((pat.ident.to_string(), &*arg.ty));
}
}
}
let is_level = hook["target"]
.as_str()
.is_some_and(|target| target.contains("::GameLevel<"));
let ticks = is_level
&& args.iter().any(|(name, ty)| {
name == "ticks" && ty.to_token_stream().to_string() == "& mut Ticks"
});
if ticks {
args.retain(|(name, _)| name != "ticks");
}
let mut used: HashSet<_> = args.iter().map(|(name, _)| name.clone()).collect();
let mod_list = fresh_name("mods", &mut used);
let mod_item = fresh_name("mod_hook", &mut used);
let replacement = fresh_name("replacement", &mut used);
let contract = api["contract"].as_str().ok_or("contract missing")?;
let out = api.get("out").and_then(|v| v.as_str());
if !matches!(
(contract, out),
("cancel" | "replace" | "collect", Some(_)) | ("listen", None)
) {
return Err(format!("invalid contract for {name}"));
}
let output = if let Some(out) = out {
let index = args
.iter()
.position(|(n, _)| n == out)
.ok_or_else(|| format!("missing output {out} in {name}"))?;
Some(args.remove(index))
} else {
None
};
let result = if let Some((_, ty)) = &output {
let Type::Reference(reference) = ty else {
return Err(format!("output must be a mutable reference in {name}"));
};
if reference.mutability.is_none() {
return Err(format!("output must be a mutable reference in {name}"));
}
match contract {
"cancel" if reference.elem.to_token_stream().to_string() == "bool" => {
" -> Flow".to_owned()
}
"replace" => format!(" -> {}", reference.elem.to_token_stream()),
"collect" => String::new(),
_ => return Err(format!("unexpected output type for {name}")),
}
} else {
String::new()
};
let host = host_for(is_level, receiver_mut, ticks)
.map(|(name, ty)| (fresh_name(name, &mut used), ty));
let event = fresh_name("event", &mut used);
let event_type = format!(
"{}Event",
name.split('_')
.map(|word| word[..1].to_uppercase() + &word[1..])
.collect::<String>()
);
let mut trait_params = vec!["&self".to_owned()];
let mut dispatch_params = Vec::new();
let mut call_args = Vec::new();
if let Some((name, ty)) = &host {
trait_params.push(format!("{name}: {ty}"));
dispatch_params.push(format!("{name}: {ty}"));
call_args.push(name.clone());
}
dispatch_params.push(if is_render {
format!("{mod_list}: &[&dyn RenderHooks]")
} else {
format!("{mod_list}: &[Box<dyn Hooks>]")
});
let mut lifetimes = EventLifetimes::default();
let mut fields = String::new();
let mut inits = Vec::new();
let mut write_back = String::new();
let collected = output.as_ref().filter(|_| contract == "collect");
for (name, ty) in args.iter().chain(collected) {
dispatch_params.push(format!("{name}: {}", ty.to_token_stream()));
let (field, scalar) = lifetimes.field(ty);
fields.push_str(&format!("pub {name}: {},\n", field.to_token_stream()));
if scalar {
inits.push(format!("{name}: *{name}"));
write_back.push_str(&format!("*{name} = {event}.{name};"));
} else {
inits.push(name.clone());
}
}
if let Some((name, ty)) = output.as_ref().filter(|_| contract != "collect") {
dispatch_params.push(format!("{name}: {}", ty.to_token_stream()));
}
let (generics, elided) = match (lifetimes.a, lifetimes.b) {
(_, true) => ("<'a, 'b>", "<'_, '_>"),
(true, false) => ("<'a>", "<'_>"),
(false, false) => ("", ""),
};
trait_params.push(format!("{event}: &mut {event_type}{elided}"));
call_args.push(format!("&mut {event}"));
let unused = trait_params[1..]
.iter()
.map(|param| format!("let _ = {};", param.split(':').next().unwrap()))
.collect::<String>();
let default = match contract {
"cancel" => "Flow::Continue",
"replace" => "None",
_ => "",
};
let invoke = call_args.join(", ");
let trait_params = trait_params.join(", ");
let dispatch_params = dispatch_params.join(", ");
let trait_name = if is_render { "RenderHooks" } else { "Hooks" };
let traits = if is_render {
&mut render_traits
} else {
&mut traits
};
let dispatch = if is_render {
&mut render_dispatch
} else {
&mut dispatch
};
traits.push_str(&doc_comments(&method.attrs, name, false)?);
match (contract, out) {
("cancel", Some(out)) => traits.push_str(&format!(
"///\n/// Return `Flow::Cancel` to take it: this sets `{out}`, and later mods are skipped.\n"
)),
("replace", Some(out)) => traits.push_str(&format!(
"///\n/// Return `Some` to set `{out}`; the first mod returning `Some` wins.\n"
)),
("collect", Some(out)) => traits.push_str(&format!(
"///\n/// Every mod gets `{event}.{out}` in order and may add, change or remove {out}.\n"
)),
_ => {}
}
traits.push_str(&format!(
"fn {name}({trait_params}){result} {{ {unused} {default} }}\n"
));
dispatch.push_str(&format!(
"/// What [`{trait_name}::{name}`] is told. Fields may be added: the struct is `#[non_exhaustive]`.\n#[non_exhaustive]\npub struct {event_type}{generics} {{\n{fields}}}\n"
));
let build = format!("let mut {event} = {event_type} {{ {} }};", inits.join(", "));
let body = match contract {
"cancel" => format!(
"if *{o} {{ return; }} {build} for {mod_item} in {mod_list} {{ if matches!({mod_item}.{name}({invoke}), Flow::Cancel) {{ *{o} = true; break; }} }} {write_back}",
o = out.unwrap()
),
"replace" => format!(
"if {o}.is_some() {{ return; }} {build} for {mod_item} in {mod_list} {{ if let Some({replacement}) = {mod_item}.{name}({invoke}) {{ *{o} = Some({replacement}); break; }} }} {write_back}",
o = out.unwrap()
),
_ => format!(
"{build} for {mod_item} in {mod_list} {{ {mod_item}.{name}({invoke}); }} {write_back}"
),
};
dispatch.push_str(&format!(
"pub fn dispatch_{name}({dispatch_params}) {{ {body} }}\n"
));
}
if seen.is_empty() {
return Err("no mod API contracts".into());
}
let code = format!(
"// @generated by cargo run -p xtask -- mod-api; do not edit.\nuse super::*;\npub trait Hooks: Send + Sync {{\nfn render(&self) -> Option<&dyn RenderHooks> {{ None }}\n{traits}}}\n{dispatch}"
);
let api_source = fs::read_to_string(root.join("crates/horizon-client/src/mod_api.rs"))
.map_err(|e| e.to_string())?;
let exports = exported_types(&api_source, &code)?;
let mut game = Vec::new();
game_methods(
&root.join("crates/horizon-client/src/game"),
"horizon_client::game",
&mut game,
)?;
let mut host_traits = String::new();
let mut host_impl = String::new();
let mut names = HashSet::new();
for helper in catalog["helpers"]
.as_array()
.ok_or("catalog helpers must be an array")?
{
let name = helper["name"].as_str().ok_or("helper name missing")?;
if !names.insert(name) {
return Err(format!("duplicate helper {name}"));
}
let native = format!("native_{name}");
let target = helper["target"].as_str().ok_or("helper target missing")?;
let method = one_function(game.iter().map(|(_, method)| method), &native)?;
let (module, _) = game
.iter()
.find(|(_, other)| std::ptr::eq(other, method))
.expect("the method was found in the list");
let expected = format!("{module}::Game<'_>::{native}");
if target != expected {
return Err(format!(
"wrong target for helper {name}: {target}, it is {expected}"
));
}
let (declaration, implementation) = host_method(method, name, &exports)?;
host_traits.push_str(&declaration);
host_impl.push_str(&implementation);
}
struct StdTypes {
path_buf: bool,
arc: bool,
}
impl<'ast> Visit<'ast> for StdTypes {
fn visit_type_path(&mut self, ty: &'ast syn::TypePath) {
if ty.path.segments.len() == 1 {
self.path_buf |= ty.path.segments[0].ident == "PathBuf";
self.arc |= ty.path.segments[0].ident == "Arc";
}
syn::visit::visit_type_path(self, ty);
}
}
let host_trait: syn::ItemTrait = syn::parse_str(&format!("trait Host {{ {host_traits} }}"))
.map_err(|e| format!("generated Host: {e}"))?;
let mut std_types = StdTypes {
path_buf: false,
arc: false,
};
std_types.visit_item_trait(&host_trait);
let mut imports = String::new();
if std_types.path_buf {
imports.push_str("use std::path::PathBuf;\n");
}
if std_types.arc {
imports.push_str("use std::sync::Arc;\n");
}
let host = format!(
"// @generated by cargo run -p xtask -- mod-api; do not edit.\nuse super::*;\n{imports}/// Services supplied by the game to trait mods.\npub trait Host {{\n{host_traits}}}\n"
);
let implementation = format!(
"// @generated by cargo run -p xtask -- mod-api; do not edit.\nuse horizon_client::mod_api::*;\n{imports}impl Host for super::Game<'_> {{\n{host_impl}}}\n"
);
let render_code = format!(
"// @generated by cargo run -p xtask -- mod-api; do not edit.\nuse super::*;\npub trait RenderHooks: Send + Sync {{\n{render_traits}}}\n{render_dispatch}"
);
for (relative, code) in [
(
"crates/horizon-client-render/src/gfx/native_render/generated.rs",
render_code,
),
("crates/horizon-client/src/mod_api/generated.rs", code),
("crates/horizon-client/src/mod_api/generated_host.rs", host),
(
"crates/horizon-client/src/game/mod_api_host_generated.rs",
implementation,
),
] {
// Parse before formatting, so invalid catalog names or types fail without writing output.
syn::parse_file(&code).map_err(|e| format!("generated Rust: {e}"))?;
let mut child = Command::new("rustfmt")
.args(["--emit", "stdout", "--edition", "2021"])
.stdin(std::process::Stdio::piped())
.stdout(std::process::Stdio::piped())
.spawn()
.map_err(|e| e.to_string())?;
use std::io::Write;
child
.stdin
.take()
.ok_or("rustfmt stdin")?
.write_all(code.as_bytes())
.map_err(|e| e.to_string())?;
let formatted = child.wait_with_output().map_err(|e| e.to_string())?;
if !formatted.status.success() {
return Err("rustfmt failed".into());
}
let path = root.join(relative);
if check {
if fs::read(&path).map_err(|e| e.to_string())? != formatted.stdout {
return Err("mod API output is stale; run cargo run -p xtask -- mod-api".into());
}
} else {
fs::create_dir_all(path.parent().ok_or("output parent missing")?)
.map_err(|e| e.to_string())?;
fs::write(path, formatted.stdout).map_err(|e| e.to_string())?;
}
}
Ok(())
}
#[cfg(test)]
mod tests {
use quote::ToTokens;
use std::sync::{Arc, Mutex};
use std::time::Duration;
struct ItemStack;
struct BlockEntityDraw(Vec<u32>);
#[allow(dead_code)]
mod stubs {
#[derive(Clone, Copy, Debug, PartialEq)]
pub(super) struct BlockStateId;
#[derive(Clone, Copy)]
pub(super) struct FluidState;
pub(super) struct PlacementContext;
#[derive(Clone, Copy)]
pub(super) struct BlockPos;
#[derive(Clone, Copy)]
pub(super) struct BlockId;
#[derive(Clone, Copy)]
pub(super) struct Direction;
#[derive(Clone, Copy)]
pub(super) struct LevelDimension;
pub(super) struct Ticks;
pub(super) trait LevelHost {}
pub(super) trait LevelTicksHost: LevelHost {}
pub(super) trait LevelRandomHost: LevelHost {}
pub(super) trait LevelWriteHost: LevelTicksHost + LevelRandomHost {}
pub(super) struct Compound;
pub(super) type NativeDispensed = (Option<super::ItemStack>, i32);
pub(super) struct NativeLootDrops<'a>(pub &'a ());
pub(super) struct NativeScreenView<'a>(pub &'a ());
pub(super) struct Corners;
pub(super) struct HudBatch;
pub(super) struct NativeBlockRim;
pub(super) struct NativeColoredLight;
pub(super) struct NativeMinimap;
pub(super) struct NativeMod;
pub(super) struct NativePanelEvent;
pub(super) struct NativeScreen;
pub(super) struct ModBlockEntity;
pub(super) struct ModContainer;
pub(super) struct ModFluidTanks;
pub(super) struct NativeCommand;
pub(super) struct NativeLifecycleContext;
pub(super) struct NativeServerPlayer;
#[derive(Clone, Copy)]
pub(super) struct ServerTickPhase;
#[derive(Clone, Copy)]
pub(super) struct WorldPhase;
}
use serde_json::{Map, Value};
use stubs::*;
struct Text;
#[derive(Debug, PartialEq)]
struct NativeZoom(u32);
enum Flow {
Continue,
Cancel,
}
trait Host {}
trait RenderHooks {}
struct TestHost;
impl Host for TestHost {}
#[allow(dead_code)]
mod generated {
mod horizon_client {
pub mod hud_layout {
pub struct HealthInputs;
pub struct GuiDraw;
}
}
include!(concat!(
env!("CARGO_MANIFEST_DIR"),
"/../crates/horizon-client/src/mod_api/generated.rs"
));
}
use generated::*;
struct Mod {
id: u32,
calls: Arc<Mutex<Vec<u32>>>,
}
impl Hooks for Mod {
fn block_entity_submit(&self, _: &dyn Host, event: &mut BlockEntitySubmitEvent<'_>) {
assert_eq!(event.pos, [1, 2, 3]);
assert_eq!(event.block, "example:machine");
event.draw.0.push(self.id);
}
fn loot_table_load(&self, event: &mut LootTableLoadEvent<'_>) {
event.table.as_array_mut().unwrap().push(self.id.into());
}
fn modify_default_components(&self, event: &mut ModifyDefaultComponentsEvent<'_>) {
let value = event
.components
.entry("order")
.or_insert_with(|| serde_json::json!([]));
value.as_array_mut().unwrap().push(self.id.into());
}
fn level_tick_pre(&self, _: &mut dyn Host, _: &mut LevelTickPreEvent<'_>) {
self.calls.lock().unwrap().push(self.id);
}
fn tooltip(&self, _: &dyn Host, event: &mut TooltipEvent<'_>) {
event.lines.push((Text, self.id));
}
fn zoom(&self, _: &dyn Host, _: &mut ZoomEvent) -> Option<NativeZoom> {
self.calls.lock().unwrap().push(self.id);
Some(NativeZoom(self.id))
}
fn should_apply_effect_tick_this_tick(
&self,
_: &dyn Host,
event: &mut ShouldApplyEffectTickThisTickEvent<'_>,
) {
event.apply = !event.apply;
self.calls.lock().unwrap().push(self.id);
}
fn living_incoming_damage(&self, event: &mut LivingIncomingDamageEvent<'_>) -> Flow {
event.amount = event.amount * 2.0 + self.id as f32;
if self.id == 2 {
Flow::Cancel
} else {
Flow::Continue
}
}
fn use_item_on(&self, _: &mut dyn Host, _: &mut UseItemOnEvent<'_>) -> Flow {
self.calls.lock().unwrap().push(self.id);
if self.id == 1 {
Flow::Cancel
} else {
Flow::Continue
}
}
}
#[test]
fn block_entity_submit_dispatches_in_order_with_shared_draw() {
let calls = Arc::new(Mutex::new(Vec::new()));
let mods: Vec<Box<dyn Hooks>> = vec![
Box::new(Mod {
id: 1,
calls: calls.clone(),
}),
Box::new(Mod { id: 2, calls }),
];
let mut draw = BlockEntityDraw(Vec::new());
dispatch_block_entity_submit(
&TestHost,
&mods,
[1, 2, 3],
"example:machine",
BlockStateId,
&ModBlockEntity,
&mut draw,
);
assert_eq!(draw.0, [1, 2]);
}
#[test]
fn host_mapping_preserves_access_and_docs_and_rejects_unavailable_types() {
let exports = super::exported_types(
"pub use external::{Visible, Original as Renamed}; pub struct Defined; struct Hidden;",
"pub struct Generated;",
)
.unwrap();
for ty in ["Visible", "Renamed", "Defined", "Generated"] {
let method: syn::ItemFn =
syn::parse_str(&format!("fn native_test(&self, value: {ty}) {{ }}")).unwrap();
assert!(super::host_method(&method, "test", &exports).is_ok());
}
let foreign: syn::ItemFn =
syn::parse_quote! { fn native_foreign(&self, value: elsewhere::Visible) {} };
assert!(super::host_method(&foreign, "foreign", &exports).is_err());
let hidden_trait: syn::ItemFn =
syn::parse_quote! { fn native_hidden(&self, value: &dyn Hidden) {} };
assert!(super::host_method(&hidden_trait, "hidden", &exports).is_err());
let read: syn::ItemFn = syn::parse_quote! {
/// Read a value exactly.
///
/// Keep the blank line too.
fn native_read(&self, pos: [i32; 3]) -> String { todo!() }
};
let (declaration, implementation) = super::host_method(&read, "read", &exports).unwrap();
assert!(
declaration.contains("/// Read a value exactly.\n///\n/// Keep the blank line too.")
);
assert!(declaration.contains("& self"));
assert!(implementation.contains("self.native_read(pos)"));
let write: syn::ItemFn = syn::parse_quote! {
fn native_write(&mut self, value: i32) { }
};
let (declaration, _) = super::host_method(&write, "write", &exports).unwrap();
assert!(declaration.contains("& mut self"));
let private: syn::ItemFn = syn::parse_quote! {
fn native_private(&self, value: BinOnly) { }
};
assert!(
super::host_method(&private, "private", &exports)
.unwrap_err()
.contains("BinOnly")
);
let generic: syn::ItemFn = syn::parse_quote! {
fn native_generic<T>(&self, value: T) { }
};
assert!(
super::host_method(&generic, "generic", &exports)
.unwrap_err()
.contains("object-safe")
);
let callback: syn::ItemFn = syn::parse_quote! {
fn native_callback(&self, callback: impl FnOnce()) { }
};
assert!(
super::host_method(&callback, "callback", &exports)
.unwrap_err()
.contains("object-safe")
);
let asynchronous: syn::ItemFn = syn::parse_quote! {
async fn native_async(&self) { }
};
assert!(
super::host_method(&asynchronous, "async", &exports)
.unwrap_err()
.contains("object-safe")
);
}
#[test]
fn lookup_rejects_missing_and_duplicate_functions() {
let first: syn::ItemFn = syn::parse_quote! { fn native_example() {} };
let other: syn::ItemFn = syn::parse_quote! { fn unrelated() {} };
assert!(super::one_function([&other].into_iter(), "native_example").is_err());
assert!(super::one_function([&first, &other].into_iter(), "native_example").is_ok());
assert!(super::one_function([&first, &first].into_iter(), "native_example").is_err());
}
#[test]
fn placement_replacement_can_refuse_and_stops_later_mods() {
struct Level;
impl LevelHost for Level {}
struct Refuse(Arc<Mutex<Vec<u32>>>, u32);
impl Hooks for Refuse {
fn state_for_placement(
&self,
_: &dyn LevelHost,
_: &mut StateForPlacementEvent<'_>,
) -> Option<Option<BlockStateId>> {
self.0.lock().unwrap().push(self.1);
Some(None)
}
}
let calls = Arc::new(Mutex::new(Vec::new()));
let mods: Vec<Box<dyn Hooks>> = vec![
Box::new(Refuse(calls.clone(), 1)),
Box::new(Refuse(calls.clone(), 2)),
];
let mut answer = None;
dispatch_state_for_placement(
&Level,
&mods,
LevelDimension,
BlockStateId,
&PlacementContext,
FluidState,
&mut answer,
);
assert_eq!(answer, Some(None));
assert_eq!(*calls.lock().unwrap(), vec![1]);
dispatch_state_for_placement(
&Level,
&mods,
LevelDimension,
BlockStateId,
&PlacementContext,
FluidState,
&mut answer,
);
assert_eq!(*calls.lock().unwrap(), vec![1]);
}
#[test]
fn generated_locals_do_not_shadow_hook_arguments() {
let mut used = ["mods", "mods_", "mod_hook", "replacement", "host"]
.into_iter()
.map(str::to_owned)
.collect();
assert_eq!(super::fresh_name("mods", &mut used), "mods__");
assert_eq!(super::fresh_name("mod_hook", &mut used), "mod_hook_");
assert_eq!(super::fresh_name("replacement", &mut used), "replacement_");
assert_eq!(super::fresh_name("host", &mut used), "host_");
}
#[test]
fn level_hosts_match_receiver_mutability() {
assert_eq!(
super::host_for(true, Some(false), false),
Some(("level", "&dyn LevelHost".into()))
);
assert_eq!(
super::host_for(true, Some(true), false),
Some(("level", "&mut dyn LevelRandomHost".into()))
);
assert_eq!(
super::host_for(true, Some(false), true),
Some(("level", "&mut dyn LevelTicksHost".into()))
);
assert_eq!(
super::host_for(true, Some(true), true),
Some(("level", "&mut dyn LevelWriteHost".into()))
);
assert_eq!(super::host_for(true, None, false), None);
assert_eq!(
super::host_for(false, Some(true), false),
Some(("host", "&mut dyn Host".into()))
);
}
#[test]
fn event_fields_name_their_lifetimes() {
for (ty, field, scalar, a, b) in [
(
"& mut WorldDrawn < '_ >",
"& 'a mut WorldDrawn < 'b >",
false,
true,
true,
),
("& str", "& 'a str", false, true, false),
(
"& mut Vec < (& 'static str , u32) >",
"& 'a mut Vec < (& 'static str , u32) >",
false,
true,
false,
),
(
"Option < & ItemStack >",
"Option < & 'a ItemStack >",
false,
true,
false,
),
("u32", "u32", false, false, false),
("& mut f32", "f32", true, false, false),
(
"& mut Option < bool >",
"& 'a mut Option < bool >",
false,
true,
false,
),
] {
let mut lifetimes = super::EventLifetimes::default();
let (field_type, is_scalar) = lifetimes.field(&syn::parse_str(ty).unwrap());
assert_eq!(field_type.to_token_stream().to_string(), field);
assert_eq!((is_scalar, lifetimes.a, lifetimes.b), (scalar, a, b));
}
}
#[test]
fn generated_output_is_current() {
super::run(true).unwrap();
}
#[test]
fn contracted_hook_requires_dispatch_call() {
let missing: syn::ImplItemFn = syn::parse_quote! { fn native_zoom(&self) { unrelated(); } };
let present: syn::ImplItemFn = syn::parse_quote! { fn native_zoom(&self) { horizon_client::mod_api::dispatch_zoom(); } };
assert!(!super::has_call(&missing.block, "dispatch_zoom"));
assert!(super::has_call(&present.block, "dispatch_zoom"));
}
#[test]
fn dispatch_contracts() {
let calls = Arc::new(Mutex::new(Vec::new()));
let mods: Vec<Box<dyn Hooks>> = (1..=2)
.map(|id| {
Box::new(Mod {
id,
calls: calls.clone(),
}) as Box<dyn Hooks>
})
.collect();
let mut table = serde_json::json!([]);
dispatch_loot_table_load(&mods, "table", &mut table);
assert_eq!(table, serde_json::json!([1, 2]));
let mut components = Map::new();
dispatch_modify_default_components(&mods, "item", &mut components);
assert_eq!(components["order"], serde_json::json!([1, 2]));
let mut host = TestHost;
dispatch_level_tick_pre(&mut host, &mods, "overworld");
assert_eq!(*calls.lock().unwrap(), [1, 2]);
calls.lock().unwrap().clear();
let mut zoom = None;
dispatch_zoom(&host, &mods, &mut zoom);
assert_eq!(zoom, Some(NativeZoom(1)));
assert_eq!(*calls.lock().unwrap(), [1]);
calls.lock().unwrap().clear();
dispatch_zoom(&host, &mods, &mut zoom);
assert!(calls.lock().unwrap().is_empty());
let mut lines = Vec::new();
dispatch_tooltip(&host, &mods, &ItemStack, &mut lines);
assert_eq!(lines.iter().map(|line| line.1).collect::<Vec<_>>(), [1, 2]);
let mut apply = false;
calls.lock().unwrap().clear();
dispatch_should_apply_effect_tick_this_tick(&host, &mods, "effect", 0, 0, &mut apply);
assert!(!apply);
assert_eq!(*calls.lock().unwrap(), [1, 2]);
let mut amount = 1.0;
let mut canceled = false;
dispatch_living_incoming_damage(
&mods,
0,
"kind",
"damage",
0,
0,
&mut amount,
&mut canceled,
);
// Each mod sees the one before: (1 × 2 + 1) × 2 + 2, kept though mod 2 cancels.
assert_eq!(amount, 8.0);
assert!(canceled);
let chained: Vec<Box<dyn Hooks>> = [1, 3]
.map(|id| {
Box::new(Mod {
id,
calls: calls.clone(),
}) as Box<dyn Hooks>
})
.into();
let mut amount = 1.0;
let mut canceled = false;
dispatch_living_incoming_damage(
&chained,
0,
"kind",
"damage",
0,
0,
&mut amount,
&mut canceled,
);
assert_eq!(amount, 9.0);
assert!(!canceled);
calls.lock().unwrap().clear();
let mut claimed = false;
dispatch_use_item_on(&mut host, &mods, &ItemStack, [0; 3], [0; 3], &mut claimed);
assert!(claimed);
assert_eq!(*calls.lock().unwrap(), [1]);
calls.lock().unwrap().clear();
dispatch_use_item_on(&mut host, &mods, &ItemStack, [0; 3], [0; 3], &mut claimed);
assert!(calls.lock().unwrap().is_empty());
}
}