diff --git a/README.md b/README.md index 8344fc09d..5f177c15a 100644 --- a/README.md +++ b/README.md @@ -36,6 +36,19 @@ This mod is [licensed under the **MIT license**](https://github.com/MightyPirate OpenComputers generates floppy disks in dungeon chests that can contain data from a selection of 'loot' directories. For example, the IRC client and the Better Shell (besh) are two programs that can be found on such loot disks. If you'd like to contribute a program that can be found this way, please have a look at [the loot readme][loot], which explains how to add custom loot. Simply pull request your loot! 4. **Core Scripts** If you would like to contribute scripts to the "core" Lua code (which basically defines 'OpenOS'), please have a look at the [code conventions][] for Lua to save us all some time. Bug fixes are always welcome. Additional programs and features should be kept small. Bigger programs (rule of thumb: larger than 3KiB) should go onto loot disks. +5. **Drivers** + As of OC 1.4, mod interaction that was previously provided by OpenComponents it now fully integrated into OC itself. If you wish to contribute a drivers for blocks from other mods, cool! Have a look at the [integration][] package to get an idea of how to structure modules and read the readme in that package for more information (in particular on additional criteria to get your PR merged). + +####Pull requests +The following are a few quick guidelines on pull requests. That is to say they are not necessarily *rules*, so there may be exceptions and all that. Just try to stick to those points as a baseline. +- Make sure your code is formatted properly. +- Make sure it builds and works. +- Try to keep your changes as minimal as possible. In particular, no whitespace changes in existing files, please. +- Feel free to code in Java, but don't be surprised if I convert it to Scala later on, if I feel it makes the code more concise ;-) +- When adding mod dependencies, keep them *weak*, i.e. make sure OC still works without that mod. Also, prefer adding a gradle dependency over adding API class files to the repo. +- Squash your commits! + +Also, and this should go without saying, your contributed code will also fall under OC's license, unless otherwise specified (in the super rare case of adding third-party stuff, add the according license information as a `LICENSE-???` file, please). ## Extending ### In your own mod @@ -88,3 +101,4 @@ Open the project and you will be asked to *import the Gradle project* (check you [releases]: https://github.com/MightyPirates/OpenComputers/releases [robot names]: https://github.com/MightyPirates/OpenComputers/blob/master-MC1.7.10/src/main/resources/assets/opencomputers/robot.names [wiki]: https://ocdoc.cil.li/ +[integration]: https://github.com/MightyPirates/OpenComputers/tree/master-MC1.7.10/src/main/scala/li/cil/oc/integration diff --git a/src/main/scala/li/cil/oc/integration/Mods.scala b/src/main/scala/li/cil/oc/integration/Mods.scala index 9b98c3dac..be2ec2b04 100644 --- a/src/main/scala/li/cil/oc/integration/Mods.scala +++ b/src/main/scala/li/cil/oc/integration/Mods.scala @@ -97,8 +97,7 @@ object Mods { tryInit(integration.wrsve.ModWRSVE) // Register the general IPeripheral driver last, if at all, to avoid it - // being used rather than other more concrete implementations, such as - // is the case in the Redstone in Motion driver (replaces 'move'). + // being used rather than other more concrete implementations. tryInit(integration.computercraft.ModComputerCraft) } diff --git a/src/main/scala/li/cil/oc/integration/README.md b/src/main/scala/li/cil/oc/integration/README.md new file mode 100644 index 000000000..ed4c129fe --- /dev/null +++ b/src/main/scala/li/cil/oc/integration/README.md @@ -0,0 +1,22 @@ +This package contains code use to integrate with other mods. This is usually done by implementing block drivers for other mods' blocks, or by implementing (item stack) converters. + +###General Structure +The general structure for mod integration is as follows: +- All mods' IDs are defined in `Mods.IDs` (`Mods.scala` file). +- For most mods, a `SimpleMod` instance suffices, some may require a specialized implementation. These instances are an internal way of checking for mod availablity. +- For each individual mod, there is a package with a `ModModname` class implementing the `ModProxy` interface. This class is initialized from `Mods.init()` if the mod it represents is available. +- Integration such as driver registration is performed in `ModProxy.initialize()`. + +Have a look at the existing modules for examples if that description was too abstract for you. + +###On pull requests +The basic guidelines from the main readme still apply, but I'd like to stress again that all integration must be *optional*. Make sure you properly test OC still works with and without the mod you added support for. + +An additional guideline is on what drivers should actually *do*. Drivers built into OC should, in general, err on the side of being limited. This way addons can still add more "powerful" functionality, if so desired, while the other way around would not work (addons would not be able to limit existing functionality). Here's a few rules-of-thumb: +- Drivers should primarily be used to *read* information. +- Drivers may "trigger" blocks, as long as the operation is not "physical". For example, setting the maximum energy output of a block would be fine, wheres making a block drop an item from its inventory would not - unless that block is providing such functionality itself, such as a dispenser (remember, *guidelines* :-P). +- Drivers should respect the mod they add integration for. For example, MFR has "mystery" safari nets - it should not be possible to read the contents of those. +- Drivers and converters should avoid exposing "implementation detail". This includes things such as actual block and item ids, for example. +- If there is an upgrade for it, don't write a driver for it. If you're up to it, adjust the upgrade to work in the adapter, otherwise let me know and I'll have a look. + +When in doubt, ask on the IRC or open an issue to discuss the driver you'd like to add! \ No newline at end of file