projectsandstone / sandstoneapi

Server Modding API for Minecraft.

SandstoneAPI

Server Modding API for Minecraft.

Sandstone is very inspired by SpongePowered (Some API characteristics is very similar (likely identical) to SpongePowered), and Bukkit API, but the Sandstone purpose is a bit different, Sandstone API aims to support all Minecraft Editions Platforms.

• Mc Version: 1.12.2
• SandstoneAPI Version: 1.0.0-SNAPSHOT (WIP)

What is Sandstone

Sandstone is a Server Modding API for Minecraft that aims to provide a common API to develop mods that works in multiple Minecraft Editions, Sandstone is designed to support Minecraft PE and Minecraft PC Edition. Sandstone is not a server, it's only a API, and the API is implemented by a Platform-Dependent plugin (like SandstoneBukkit, SandstoneSponge and SandstoneNukkit), Sandstone is written in Kotlin, and we plan to provide a LUA Plugin API to support non-JVM platforms like PocketMine-MP.

Supported Languages

• Java
• Kotlin (partial)
• Scala (object plugins only)

Officially supported platforms

• Bukkit
• Sponge
• Nukkit

How Sandstone works

It depends on implementation, but commonly we use Adapter pattern and weak cache some instances.

Attention

Does not compare Sandstone objects by identity (== in Java and === in Kotlin), use the equals method in Java and == in Kotlin to compare objects

Adapter delegates hashCode and equals methods to Adaptee instance.

Inconsistencies

Please report any inconsistency between platforms, Sandstone MUST be consistent between Platforms, if operation c() returns 9 in Platform A then the same operation MUST return 9 in Platform B, Platform C...

Inconsistencies MUST be reported and fixed in the implementation and not in the API or Common project.

Debug parameters

Sandstone provides debug parameters to save generated classes:

Project	Parameter	Description
EventSys	kores.generation.dir.eventsys=/save/dir	Defines class save directory
EventSys	kores.generation.save.eventsys=true	Enables global generated class save
EventSys	kores.generation.save.eventsys.factorygen=true	Enables save of factory generated class
EventSys	kores.generation.save.eventsys.eventgen=true	Enables save of event generated class
EventSys	kores.generation.save.eventsys.listenergen=true	Enables save of listener generated class
EventSys	kores.generation.save.eventsys.directgen=true	Enables save of listener generated class
KoresProxy	koresproxy.saveproxies=true	Enables save of proxy generated classes

Sandstone provides debug vm parameters to save all Sandstone generated classes: -Dsandstone.debug=true.

If you want to save only Event implementation generated classes: -Deventsys.debug=true

CodeProxy provides -Dcodeproxy.saveproxies=true to save Proxy classes

Obs: these parameters is for debug purposes only, saved classes help us to find bugs in the Code Generator, if you are not a advanced user trying to find the cause of a bug, does not use these parameters!!!

More

• CONTRIBUTING
• FAQ

sandstoneapi's Issues

Events

Events

Management & Invocation:

• EventSys

---

Event classes:

Initialization

• PreInitializationEvent
• InitiaizationEvent
• PostInitialization
• ServerStarting
• ServerStarted
• ServerStopping
• ServerStopped

Achievement

• GrantAchievementEvent

Block

• BlockEvent
• BlockChangeEvent
• BlockBurnEvent

Chat

• MessageEvent
• Channel
• MessageChannelEvent

Command

• SendCommandEvent

Entity

• EntityEvent
• EntityDamageEvent
• EntitySpawnEvent
• EntityDespawnEvent
• EntityMoveEvent
  ...

Inventory (requires: #6)

• InventoryEvent
• InventoryOpenEvent
• InventoryCloseEvent
• InventoryChangeEvent
• InventoryInteractEvent
  ...

World

• WorldEvent
• WorldLoadEvent
• WorldUnloadEvent

Command API

Document and integrate KWCommands with Sandstone.

Inventory API

TODO

A Query based Inventory API? Is easy to implement in all platforms. ItemStack list like Bukkit is hard to implement in Sponge.

Analog to SpongePowered Data API

Introduce an analog to SpongePowered Data API, the API should be possible to be implemented on Spigot/Glowstone, Sponge (this is easy), Nukkit and possible future platforms, but trying to keep the power of Data API.

Feature API

Yes, this is the limit, not everything can be implemented in every platform, Feature API will introduce possibility to use some features that are available in some platforms but not in others, removing some limits of Sandstone ecosystem.

Examples:

Feature<MakePlayerADragon> makePlayerADragonFeature = Sandstone.getPlatform().getFeature(MakePlayerADragon.class);

if (makePlayerADragonFeature.isAvailable()) {
    MakePlayerADragon makePlayerADragon = makePlayerADragonFeature.get();
}

// yes this was intentional

Split SandstoneAPI

SandstoneAPI will support MC:PE versions, and some features of MC:PC version doesn't exists in MC:PE and vice-versa, to make all Sandstone plugins compatible with MC:PE implementations, SandstoneAPI must be splitted into three projects: SandstoneAPI, SandstoneAPI_PE, SandstoneAPI_PC.

Entities

Entity classes:

• Entity
• LivingEntity

Animal:

• Animal
• Sheep
• Cow
• Horse (partial)
• MushroomCow
• Ocelot
• Pig
• PolarBear
• Rabbit
• Sheep
• Wolf

Monster:

• Monster
• Blaze
• CaveSpider
• Creeper
• Enderman
• Endermite
• Ghast
• Giant
• Guardian
• MagmaCube
• Silverfish
• Skeleton
• Slime
• Spider
• Witch
• Wither
• Zombie
• ZombiePigman

Player:

• Player
• Human

Types:

• Aerial
• Ageable
• Ambient
• Aquatic
• Creature
• Hostile
• Damageable

AI:

• Agent

Other:

• Villager
• Squid
• Bat

...

API Features

API Features:

• Plugin manager
• Service Manager
• World partial
• Entities #3 need review
• Text
• Events #2
• Scoreboard Future version
• Effects Future version
• Blocks partial
• Items partial
• Commands
• Profiles Future version
• Registry
• Expose AdapterHelper (possible feature)
  ...

It is not dead!

Last year I've joined a college class in Information Systems Bachelor field and started my internship program in a technology company. And as I'm the only maintainer of my projects and I've a bunch ideas for softwares in other fields (not only in MC), and I also have a WIP MC Mod, a YouTube series project, and so on... It becomes almost impossible to continue the development of Sandstone (and I even don't know if it worth the work), so this project seems dead... But wait, I'm going back to personal project development, and as this project is not hard to implement (at least the core concept), I will be slowly taking back the development of Sandstone too.

So please, be patient, at some point I will get back with something working, and I'll impress you, or at least try to.

Limit Generic event dispatch

The dispatch of generic events (like ChangeServiceProviderEvent<T>) is very slow, to improve the performance, generic verification will be removed. Dispatching a ChangeServiceProvider<MyService> will be the same as dispatch ChangeServiceProvider, but, the listeners generated by CodeAPI will check these types, now the generic events is limited to:

• Only supported by Listeners generated by CodeAPI, these listeners will check the event type.
• Generated listeners can only check event types if:
  • Class has a getter method that returns a object of generic type to check.
  • Class has a Class<TYPE_TO_CHECK> (like Class<T>).

With this limitations we can make a better check using Bytecode instead of TypeInfo.isAssignableFrom method (runtime verification).

Example:

class MyEvent<T> { // Can be checked because the type T can be inferred from 'type' variable.
  Class<T> type;
}

class MyEvent<T> { // Can be checked because has a getter method (getValue) that returns a object of type T
  T getValue();
}

class MyEvent<T> { // Cannot be checked because has no getter method or Class<T> variable.
  void setValue(T value);
}

This limitation will prevent the Sandstone to slowing down (more than already do) the event dispatch, but, first I must to compare the performance of current implementation with the purposed implementation before considering to remove or limit the generic dispatch.