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
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 likeEntityKnife
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.
- Find a way to make modules peristent through
include
s- 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
- Leverage global usage and meta typings to get rid of the
- Make
EntityMelee
a subclass ofEntityEffect
- Docs
- Generate webview docs from comments
- 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
- Callbacks
- Charge
- Callbacks
-
GetChargebarPosition
-
OnChargeStart
-
OnChargeUpdate
-
OnChargeFull
-
OnChargeEnd
-
OnChargeRelease
-
-
IsCharging
- Chargebar
- Callbacks
- Player input
- Callbacks
-
OnPlayerMoveStart
-
OnPlayerMoveUpdate
-
OnPlayerMoveEnd
-
OnPlayerAimStart
-
OnPlayerAimUpdate
-
OnPlayerAimEnd
-
-
IsPlayerAiming
-
IsPlayerMoving
- Callbacks
- Throw
- Callbacks
-
OnThrowStart
-
OnThrowHit
-
OnThrowEnd
-
-
IsThrown
- Throw types
- None
- Projectile
- Boomerang
- Custom ?
- Callbacks
- 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 ?
-
- Swing
- 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
MeleeWeaponApi - TBOI: Repentance script extension by Ludovic F. (aka Sir Wrexes) is licensed under CC BY 4.0