Please? Pretty Please?

extreme pwetty pweeze?

Something reminiscent of the http API from CC would be very nice.

• send messages to specific users
• broadcast messages to everyone
• color formatting parser (ideally can parse ampersand format, and tag format)

UserData handled by the factory should provide a pairs metamethod that allows the user to iterate over method name, value pairs. I think that's all we need to completely mirror functionality of a table.

Lua Reference

Require gets a string passed in. The string should be one of three things:

1. Another scripts identifier require("script-id"). This would give whatever is returned by the scripts entrypoint.
2. A path within the script calling require require("path.to.library"). This would be a path relative to the script calling require. It would give whatever's returned by the script on execution.
3. A mods provided identifier require("mod-id"). This would give whatever is returned by a mod providing an external API for use within allium. (If you are a developer and do this, I love you.)

I recall require stores loaded packages in a table packages.something... To keep compat with Lua we'll have to respect this. Shouldn't be to bad. Simply mentioning it here as a reminder to anyone attempting an implementation (ie: me)

I've had my fair share of crashes when working on mods in Allium. Generally it's been an issue with Allium logic that I've been able to work out, but sometimes it's an issue with Lua code. The errors on that front are a little less descriptive and consistent than I'd desire:

Lua compile error - does not crash game.
Lua runtime error - crashes the game.
Lua runtime error in event - does not crash game.

What's our goal? Do we want to minimize crashing if possible? Or should we just let the game crash just like how the situation would be handled in java? I'm leaning more towards the latter, since pretty regularly I'll have an event registered per-tick or per-frame which spams the log until I pause/terminate the game myself. Additionally I have a feeling that with pcall the lua user might be able to control crashing which I would be much more in favor of.

As for specific errors that I think we could expand on:

Type mismatch errors are probably the most common, and while they give a descriptive output of what types the input parameters can be for any given method, they don't provide the types that were input by the user. I think this enhancement alone could substantially improve debugging for a user. Generally the fix is just changing a dot to a colon to pass the userdata along.

Another error I think we could look into providing more details on is a fun one. When there's a public method and a field with the same name (World.isClient), the method is selected first. This is seldom an issue but when it is it's a doozy to figure out. Fortunately when there is such an issue the method returns the field value, but I can imagine some really dumb situations where that's not the case. I bet there's some fiddling we could do with __index, PropertyResolver and UserdataFactory to resolve a name like .f_name to a field name that shares a method name. There's probably a better way of going about fixing this though which I'll leave open for discussion here.

much like resource packs, allium scripts should be able to be dropped in using zip files.

Registers a command using a similar format to allium.onEvent:

allium.command("help", function(player, arg1, arg2, ...)
  chat.say(player, "no.") -- assuming chat API looks like this
end
)

Would register a command that could get called as /test:help please?. player would be the player that executed the command, or nil if it was run by a server. arg1 would be "please?", and arg2 (and the rest of the arguments) would be nil.

Get it? I'm pretending to be an average user

allium-cc had an interesting structure, but I just don't think it makes much sense. I propose a new structure that's more normal:

directory structure:

/plugins
  /<unique directory name> (can be a .zip)
    /<other directory(ies)> (will be ignored by allium, but may be used by this plugin [exclusively])
    main.lua

main.lua structure

main.lua will have to have a method on_initialize that will be called by the loader. This method will be required to return a namespace id, a plugin version (semver 2.0.0 spec), and an optional human readable name. Eg:

function on_initialize()
  --<logic registering commands, threads, and the like>
  return "allium_stem", "0.1.0", "Allium Stem"
end

Future considerations

• Plugins that may offer an API
• Plugins that depend on other plugins (and preventing cycles)
• Should plugins have a shared _G?

A more broad discussion that I think would be helpful is to take a look at allium-cc's register API. What should I keep and what should I scrap from that logic? For reference an example plugin using the allium-cc standard can be found here

With BlanketCon coming up, I thought it would be cool to create a script that offers a warp system, in the event that it's not already provided by another mod. Regardless of that, I realized that I couldn't do it if I wanted to. I'd need a way to save the warp coordinates/dimension.

I'm also adding config to this issue because they both have to do with reading/writing data external to script stuff. The API would ideally be able to handle optional values, as well as fix invalid values in a config file without overwriting it completely. Config files would be found in config/allium/<script_id>.json.

Persistence would be a bit more complicated than this. Ideally it would be a drop-in replacement of the io API, sandboxed within the directory the script is in.

This entire concept is up for discussion.

Only example mod

Documentation:

• Allium library allium
• Commands library commands
• Command builder command
• Game library game
• Java library java
• Class builder library
• NBT library nbt
• Package library package
• Require function require
• Script library script
• Text library text
• Possible yarn mappings -> lua documentation?
• Events

Tutorials:

• Allium Script Setup and Hello World
• Let's script: My first Lua Item
• Let's script: My first extended class
• Let's script: My first Lua command
• Let's script: Hangman game
• Creating an Allium API for your mod

Right now, scripts can only get information about installed mods by importing FabricLoader, which is clunky.

A directory (probably named resources) that shares the same path as the main script and manifest. Everything contained in the directory should look exactly like how it is in a Fabric mod: assets/<namespace>/..., data/<namespace>/....

Since we're parroting fabric's mod structure, maybe manifest.json should move into this directory, and should be renamed to allium.mod.json.