Skip to content

A simple and user friendly way to create melee weapon mods for The Binding Of Isaac: Repentance

License

Notifications You must be signed in to change notification settings

Wrexie-s-TBOI-mods/MeleeWeaponApi

Repository files navigation

Melee Weapon API

A user-friendly way of implementing melee weapons in mods for The Binding of Isaac: Repentance.

To use to API, with the mod installed and enabled, an global class serving as namespace is exposed: MeleeWeaponApi. Inside this class you will find a function: .Create(options), to create instances of EntityMelee.

The EntityMelee class is a subclass of EntityEffect, which means that you must provide it with the EntityVariant id of an effect, but it also means that you can you can use all properties and methods of EntityEffect and Entity as well!

EntityMelee is designed around calling specialised callbacks on various actions and states. These callbacks are all functions with a name starting with :On... and that you can override with your own code, leaving to the API most of the worries of managing game/weapon/player state and all the AddCallback logic. You still have easy access to your weapon's state, and, if you really want to, you can modify it, though I don't particularly recommend it. When one such callback is run during the execution of a ModCallback, the corresponding ModCallback is mentioned in its documentation and in-editor annotations under [Parent callback].

MeleeWeaponApi also contains an Util class, serving as a namespace for a whole bunch of neat little functions designed to make code more readable while also reducing boilerplate.

To access all the types and in-editor documentation, it is recommended to download the Types, and copy it anywhere into your mod's folder under any name you like, e.g. path/to/game/mods/My AWESOME mod/MWA types. A Virtual Studio Code extension might come in the future to rid the need for this step.

Full documentation and examples comming soon:tm:.

Requirements:

  • Afterbirth+ and Repentance
  • Repentogon

FAQ*

What did you use to make this ?
VS Code and the Binding of Isaac extension, StyLua for formatting and Selene for code linting.

Can I use it for my mod ?
Of course, that's what it's made for !
Just make sure to mention the API somewhere in the mod's description, I'd love for more people to find it. 😊

Can I help you develop the API ?
Sure, if you find any bugs or if you have some feature/improvement proposal, you're welcome to open a PR and I will gladly take a look at it !

What was your motivation to make this ?
Well, I wanted to make my first mod a character with a melee weapon. I tried using things from the game like EntityKnife but didn't get anything good.
So I looked and asked on Discord for any kind of existing API to make weapons easily and my search yielded no results.
Why not just make that my first mod, and then use it in my second mod, you know ?

Hey, just wondering if you got your photos printed?
bogos binted ?

*Nobody asked anything about this API so I faked some "interesting" questions.


TODOs in appromixate order of priority

  • Find a way to make modules peristent through includes
    • Leverage global usage and meta typings to get rid of the x = mod.__x or include "..." // mod.__x = x pattern
    • Prevent registering the same callbacks repeatedly on luamod
  • Make EntityMelee a subclass of EntityEffect
  • Docs
    • Generate webview docs from comments
      • LuaDox: Requires doubling every @param or @return with @tparam or @treturn
      • LuaLS: Completely undocummented and clunky, couldn't get it to work, though potentially best option. Look into #2977 #2997
    • Doc-comment everything
    • Mention parent ModCallback that runs EntityMelee property callbacks (useful for things like tick rate etc)
  • EntityMelee
    • Swing
      • Callbacks
        • OnSwingStart
        • OnSwingHit
        • OnSwingEnd
      • IsSwinging
      • Animate
      • Swing target discriminator
    • Charge
      • Callbacks
        • GetChargebarPosition
        • OnChargeStart
        • OnChargeUpdate
        • OnChargeFull
        • OnChargeEnd
        • OnChargeRelease
      • IsCharging
      • Chargebar
    • Player input
      • Callbacks
        • OnPlayerMoveStart
        • OnPlayerMoveUpdate
        • OnPlayerMoveEnd
        • OnPlayerAimStart
        • OnPlayerAimUpdate
        • OnPlayerAimEnd
      • IsPlayerAiming
      • IsPlayerMoving
    • Throw
      • Callbacks
        • OnThrowStart
        • OnThrowHit
        • OnThrowEnd
      • IsThrown
      • Throw types
        • None
        • Projectile
        • Boomerang
        • Custom ?
    • Sprite rotation
      • :Rotate() — I still don't know if rotating the effect with the sprite is necessary
      • :SmoothRotate()
      • User friendly interpolation formula integration — with default(s)
        • Bézier generator ?
  • Lock API metatables Note: For convenience and dev flexibility, this should be done at the end
  • VS Code extension
  • Test suites
  • Github Actions
    • Doc generation
    • Releases
    • Changelog
  • Lose The Game

License

MeleeWeaponApi - TBOI: Repentance script extension by Ludovic F. (aka Sir Wrexes) is licensed under CC BY 4.0

About

A simple and user friendly way to create melee weapon mods for The Binding Of Isaac: Repentance

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages