epfly6 / repentanceapiissuetracker Goto Github PK

Mod shaders in AB+ are very hard to work with, and are missing important features. Of note:

• Being unable to use GLSL features after the very first version, including arrays and others, in all GPUs due to the version line being unusable (I assume because the XML code gets injected after line 1 in the actual shader code)
• Being unable to load images and game data to mask out effects, apply them only on certain entities/stage portions, etc
• Probably being more laggy than vanilla ones? That one is probably as much on my side as the game's, though

Another useful but less important feature would be being able to 100% disable them via code (instead of still loading them and using a GLSL variable to do so), so an option could be added for users with less powerful machines, else they seem to still have a performance impact

(Note: I am not too proficient with shaders in other contexts myself, so if someone more knowledgeable can add on this please do)

Using any of the "Use" functions on the EntityPlayer class (UseActiveItem/UseCard/UsePill) will crash the game on the pre-api repentance build (not sure if we should be adding these here but it may be useful for tracking).

Certain resources (such as UI graphics) are cached on startup, and can only be affected when initially loading the game. As such, enabling/disabling mods that affect these resources cause no effect until restarting the game, which can be confusing to some users.

In the AB+ API, tears fired by familiars don't send an MC_POST_TEAR_UPDATE callback for that tear when fired, despite player tears doing so. All tears begin properly sending MC_POST_TEAR_UPDATE callbacks after the first frame of existing.

Including a bosscolors.xml in the content folder does not merge it with the base game's bosscolors.xml.

This makes adding new champion forms of base game bosses difficult, although it is still possible to override bosscolors.xml in resources, at the cost of mod compatibility.

The classic download failure! When you open the game after subscribing to several mods and steam downloads them, the game attempts to copy the mod files over, rather slowly. If the game is interacted with at this point, it will be deemed unresponsive, and prompt you to close it or wait it out.

If you choose to close the game while mods are being copied, it will interrupt the copy, meaning many of the mod's files may simply not exist like they are meant to. If this happens after metadata.xml is copied, it won't even try to update the mod and correct the issue upon re-opening, instead requiring you to delete the whole mod folder to fix it.

Entity.SpawnerType and Entity.SpawnerVariant work as intended and show the .Type and .Variant of the spawner of that entity, if that entity indeed has a spawner. It's odd for Entity.SpawnerEntity to be nil in that case.

Entity.Position always returns Vector(0,0) in INIT callbacks and isn't useable for some of the needed calculations that an entity needs on init where position is relevant. This is bypassed using the first frame of the update callbacks in mods, which isn't ideal. It however is still possible to set the entity's position successfully in the INIT callbacks.

Currently, any mod that wishes to change the HUD must either abuse the no HUD seed or remove all of the graphics relevant to the HUD from the game files, and even if you do change the HUD, your sprites will not be rendered correctly alongside other sprites unless you also ask the user to tell you what their HUD Offset setting is somehow.

Ideally, we'd be able to prevent certain HUD elements from rendering via a callback or similar. Depending on how much fine control we have, we could:

• Stop the rendering of the streaks that announce items, floors, or minibosses, and render our own instead.
• Stop the rendering of individual hearts, and render our own custom heart types in their place.
• Easily create HUD overhaul mods that overhaul individual parts of the HUD visually.
• Render custom minimaps with special rendering rules for rooms.

The game does not disable continuing under any circumstance, meaning any time a mod is removed a run can still exist with item or character ids or similar that are invalid.

A notable example is that playing a run with only one character mod installed, exiting the run, then disabling the character mod will cause the continue button to crash the game when selected.

On AB+, we already lacked this, but it wasnt much of a problem since the shaders were often minor and did not apply to every layer of rendering. In repentance, however, this starts to become a problem, specially with mods that use or gravitate towards menus, since the menus are also affected for said shaders giving some unexpected results (like getting blind going in burning basement, lol).
An option to temporary disable shaders could help, since one could disable them on menu open and disable them on close, but this would still be an issue for mods that render stuff on the hud or have menus that stay open...the other alternative, which imo is better but sounds harder to implement, would be a way to render sprites over the shader layer (an extra param on the Render function?).

Entity.DepthOffset changes it's DepthOffset to always go in front of all other entities if a number too low or too high is put in, while it preferably would go behind most other entities if a high negative number is put in for instance.

According to my finding this only happens once the .Y position of the entity added up with the .DepthOffset of the entity goes outside of the room perimeters, meaning that for an entity at the very top of the room DepthOffset could bug out when it's -200, while that wouldn't be any issue at all for entities at lower altitudes of the room.

Being able to animate player costumes through code would greatly simply the creation of charged items and recreation of similar base game features, like Breath of Life's costume.

Naturally because of how the costume system works, it's sometimes impossible to animate the player's costume and make a visible charge animation. The base game gets around this by making the player flash colors instead, which would also be nice to have easy access to.

Intended behavior: should remove item from player
Result: crash

It would be very useful to get data from the current savegame file. This includes:

• Item "touched"/collected progress
• Unlock Progress of achievements, bosses, etc.
• Stats like Killcounts, ...

Every medium-to-large mod uses require() in order to break up their mod into separate files.
So, this bug makes testing mods a pain in the ass, forcing an entire game reload.
The luamod console command is also utilized by automatic-mod-reloading tooling, such as in IsaacScript.

The base game uses various features to taper the effects of Damage and Tears upgrades, which we do not have access to.

The base game's formulas (or at least an accurate reimplementation of them) for the Damage and Tears stats can be found on the Isaac wiki.

We are missing access to:

• The base damage stat that enters the formula
• The overall damage multiplier
• The base tears stat that enters the formula
• The current tears cap (adjusted for things like soy milk)
• The new repentance range stat

Currently, it's impossible to edit any of the data contained within the base game's XML files without overwriting the entire file.

This notably makes mods prone to breaking when the game updates, and any two mods which overwrite an XML file are inherently incompatible with one another, unless they happen to make the same changes.

If it were possible to patch over existing entries in some other way, many things could be greatly simplified, such as:

• Changing the HP, name, size, animation, or tags of any entity
• Removing or adjusting the weights of items in item pools
• Changing item descriptions, names, sprites, or health effects

On the MC_POST_NPC_DEATH GetData() gets you an empty table instead of the real entity data table(that still exists, you just cannot access it with the api unless you store a reference to it prior to the npc's death).

Implementing custom weapon types is one of the most harrowing tasks in the API, because it requires carefully interfering with every other weapon type.

Currently, it's possible to prevent the player from shooting by giving them an extremely high fire delay, but this comes with costume issues (Isaac's eyes remain permanently closed) and does not work for weapon types like Ludovico that are always out.

Used this function inside MC_FAMILIAR_UPDATE callback with Isaac.Spawn(). Removing ToTear() will not trigger crash.
Possily need more researching?

Because some callbacks are cancellable, you cannot always depend on your code running, or that a future callback won't cancel even after your code runs. This makes certain mod compatibility issues (and even callback order issues within the same mod) difficult to resolve.

As an example, the ENTITY_TAKE_DMG callback could be used to create a holy mantle style effect by returning false and cancelling the callback. However, if an earlier loading mod added an item that does something on taking damage, that effect would still occur because it would have no way to know that damage would be blocked. Ideally, the holy mantle effect would be on a "before" callback, that is capable of cancelling damage, while the item that does something on taking damage would be on an "after" callback, that only occurs if damage is not cancelled.

Certain items, like Trinity Shield or Spear of Destiny, lock the player's facing direction. We do not have access to this in any way, which makes creating similar effects hard or impossible.

Currently, if you want to modify a sprite from within LUA you can only do so for the entire sprite. However, there are several cases in the basegame of sprites being modified on a layer-by-layer basis (an example is tears, whose scaling effects only apply to the first layer outside of Multidimensional/Belial tears, which be seen by passing them custom ANM2s). As such, it would useful to have access to sprite layers and have the ability to modify them in methods similar to that of the basegame.

For the sake of mod compatibility especially, an EntityConfig would be immensely helpful. It would allow accessing:

• Initial and Stage HP of an entity
• Boss Armor of an entity
• Ability of an entity to be rerolled into or made into a champion
• Name of an entity

This is a big one and an obvious one, so this issue will be primarily dedicated to all of the features that come with that.

A custom stage should:

• Have a custom backdrop, custom music, custom boss / player spots, and a custom stb file to read from.
• Be possible to set as the next stage from any other stage, for the purposes of any trapdoor or similar that spawns on the current floor.
• Have a custom boss pool, that can be adjusted as needed at runtime for features such as guaranteed bosses or horsemen.

A custom backdrop should:

• Have custom grid, wall, and floor graphics
• Have optional water, and ideally be possible to adjust the rendering of manually for recreation of effects such as Dark Room's background void and water.
• Be assignable to any room as desired
• Allow for custom properties of grids within it
• Allow for custom backdrop rendering, like how the Dark Room has a special bottom face.

Custom level generation should:

• Allow adjusting the size of and reshaping altogether the general structure of floor generation.
• Allow creating new types of special rooms with their own placement rules and positioning them in the floor.
• Allow creating disconnected floor segments, like in Red Redemption, or the Downpour mirror world, or Antibirth's Mausoleum alt section.
• Allow manipulating which rooms get loaded into which positions, for things such as the Downpour white fire and mirror rooms, or for creating custom inter-room features.
• Ideally, support adjusting the floor at runtime, changing or moving or restructuring room layouts with items or as part of a stage mechanic.
• Ideally, allow floors larger than 13x13 in size.

Currently, we only have access to MC_POST_RENDER and MC_POST_<ENTITY>_RENDER callbacks, which allows us to render sprites over the entire screen (except for the HUD) and over certain entities, but is far from enough to properly render many effects.

Obvious missing render opportunities include:

• Behind the stage, for effects such as Dark Room's purple void and animated fire / water on Burning Basement / Caves / Flooded Caves / etc
• The stage itself / in front of the stage, for effects such as the Repentance path's wall decorations
• Over the floor, but behind water and similar effects, for rendering things like reflections.
• Over the floor, but under grids and all other entities, for things like decorations or creep. (Note that we can currently do this by spawning a creep entity, then changing its variant into something else and loading a new anm2 onto it.)
• Over the HUD, for effects such as gold hearts' outlines

Additionally, we can currently only use shaders on the entire screen at once, including the HUD. There are a lot of use cases for shaders since you can use them pretty much anywhere you render anything, but I'll just list a few:

• Behind the HUD, but over everything else, for stage effects like being submerged in water.
• On individual entities, like Dogma.
• On individual item sprites, also like Dogma.
• Behind the stage, on the stage itself, or over the floor of the stage, similar to the above for rendering.
• On HUD elements exclusively

The Sprite attribute of the GridEntity class acts in a pretty odd way. If you want to change the sprite rotation, lets say, doing Gent.Sprite.Rotation wont work...in order to achieve that you have to do the following currently:

local auxsprite = gent.Sprite
auxsprite.Rotation = newrotation
gent.Sprite = auxsprite

Which is unlike handling any other sprite in the api, It's like the get functions tosses you a copy of the GridEntity sprite rather than the actual reference?

When spawned, the new trail effect introduced in repentance messes up the rendered text in several ways, some text will lose it's shadow, some fonts would just become invisible entirely.
Here is a video for it since I do get that it may be a little hard to understand on just words, on this one, notice how the shadows go off when the trail spawns and after I kill the trail effects, when the tear dies, the shadows come back:

Slot machines are currently not supported at all in the api as they're missing their own EntitySlot class and even miss update/render callbacks to interact with them.

For basic slot machine support it would be nice to have:

• Callbacks for slot machine on update and render
• The EntitySlot class for functions/attributes specific to slot machines
• .State attribute with a fitting enumeration for slot machines
• Attributes/functions for reading the amount of coins paid or donated to the slot machine (when applicable)
• Functions for changing the states of the slot machine correctly (PutInCoin(), PayOut(), Break(), etc.)

Optionally for more extensive support it would be nice to have:

• Callback for when a slot machine breaks
• Callback for when a slot machine pays out
• Allowing modders to set custom rewards/payouts for slot machines

Currently, POST_UPDATE callbacks exist for most entity types. However, PRE_UPDATE callbacks only exist for NPCs. It would be useful to include more such callbacks for the other types of entities.

In most (or all?) init callbacks, many attributes are not initialized.

For example, in the MC_POST_EFFECT_INIT callback, the following attributes are either set to 0 or nil:

• Position
• SpawnerType
• SpawnerVariant
• MaxDistance

And possibly others - I have not performed an exhaustive test.

This is a problem because for many mod use-cases, it makes the init callback useless, since you generally only want your code to apply to specific things, and not all things.

As a toy example, say that you wanted to have an item that modified creep that spawned within a certain radius of the player. For this, the obvious implementation would be to use entity:GetData() to mark eligible creep with a custom attribute in the MC_POST_EFFECT_INIT callback. However, since you can't access the position, this won't work.

As a workaround, mods are forced to check for the existence of new things on every frame in the POST_UPDATE callback, which (obviously) is not ideal.

Manipulating and working around base game items is one of the most challenging things to do in the API, requiring large amounts of reimplementation and often creating fake items that create a lot of room for mod incompatibilities.

If we could disable the effects of base game items through the API, similar to the Mines secret sequence, we could:

• Disable certain weapon types in order to implement our own weapon synergies
• Tweak the effects of existing items without implementing fake ones that other mods can't interact with easily
• Fix broken interactions between modded and existing items, and add custom ones in their place

Especially for bigger mods it's nice to have unlocks so players still have something to work towards. The achievements.xml file could be used for this, granted modders can access those unlocks through lua and calling Unlock() on them when certain conditions set by the modder are met. The unlock paper would show with the .png set in the achievements.xml. Giving the option to link the unlock to items and characters would be very convenient.

More functionality like being able to do this with any existing achievements in the game, or having the ability to also lock unlocks again would also be nice to have.

Presumably the intended behavior is to show a delirium hallucination and change the backdrop, like The Void.

It might be nice to include an alternative function or console command to crash the game directly, for testing purposes.

The EntityNPC:MakeChampion function allows for converting enemies into different champions, but does not directly set any of the relevant properties like health, requiring further work, and also cannot change an enemy that is a champion into one that is not.

A current workaround for this is to morph an enemy via EntityNPC:Morph into an enemy that cannot become a champion, then morph it back and adjust all of its properties to be correct.

Intended behavior: should return iterateable list with room descriptions
Result: returns unusable userdata

When a mod updates, its folder is deleted entirely and then replaced with the one downloaded from the steam workshop. Since mod save data is stored within the mod folder, this results in it being erased, unless another mod manages to back it up.

An additional related issue is that all mod save data is lost when a mod is unsubscribed from, due again to mod save data being stored within the mod folder.

This issue was well known since the beginning of ab+.

The issue is, that the copy mechanism of the game does not work, when the Username of the windows user, aka. the user folder name, contains letters that are not in the english alphabet (ascii Charset with the basic 256 letters). It seems, that there is a conversion missing, and therefore the game cant seem to find the path to the mods folder.

Therefore, mostly Russian, or non english speaking people had to install the mods manually for many years.

Very important issue that definetly needs addressing, if not done already!

Currently, there are two methods of modifying the game over screen within the API. One method requires modifiying the death_screen.anm2 file to add your own entries for enemies/bosses and setting the animation frames as necessary in the entities2.xml file. However, this only works for the first mod that modifies the death_screen.anm2 file, and isn't very compatible with items due to their dynamic IDs. The other method requires use of an external API similar to StageAPI, and requires workarounds that have the unfortunate side-effect of breaking the Bestiary and Collection pages.

As neither of the current approaches are ideal, it would good if we instead had access to more native support for adding new item, enemy, boss, location, etc. sprites through LUA or content-patching, as is currently done for character names. This could also double as support for the Bestiary/Collection/pause screen, depending on the implementation.

This would require unlocks to be implemented like mentioned by issue #39

Preferably an opt-in system so not all modded characters need to be up to the standards of having unlocks for all completion marks. An unlock would need the functionality of being linked to a certain completion mark of a certain modded character.

Right now in the API there isn't any sort of method to change a room's Data, the only workaround we've been able to find is to overwrite their RoomDescriptorData with the one of another room. It would be nice to able to change the room's type via lua, room backdrop, among other options regarding their data.

The constructor of the Color class doesnt allow float values for the last 3 parameters (RO,GO,BO) even thought the actual values of the Color class can be floats and are used as floats.

These callbacks are:

• ModCallbacks.MC_PRE_BOMB_COLLISION
• ModCallbacks.MC_PRE_FAMILIAR_COLLISION
• ModCallbacks.MC_PRE_KNIFE_COLLISION
• ModCallbacks.MC_PRE_TEAR_COLLISION
• ModCallbacks.MC_PRE_PICKUP_COLLISION
• ModCallbacks.MC_PRE_NPC_COLLISION
• ModCallbacks.MC_PRE_PLAYER_COLLISION
• ModCallbacks.MC_PRE_PROJECTILE_COLLISION
• ModCallbacks.MC_GET_SHADER_PARAMS
• ModCallbacks.MC_PRE_NPC_UPDATE
• ModCallbacks.MC_PRE_SPAWN_CLEAN_AWARD

This issue can be resolved on the Lua side by having a mod that loads first add each of these callbacks, then hijack the AddCallback function to add functions to its own table.

Some of these callbacks allow for passing parameters like an entity id, in which case the callback only fails for that particular parameter.

Currently, grid entities are the inscrutable black box of the API. They have no xml file, and can only be edited through LUA code via limited and faulty functions.

Ideally, there would be an easily extendible way to add new grid entities and change their properties, including:

• Grids with a specific collision class
• Grids that can be destroyed by bombs
• Grids that can be destroyed by tears, and take either a certain number of hits or a randomized number of hits, like TNT and Poop respectively.
• Grids that do things upon destruction, like spawn pickups or explode.
• Doors that can take the player to arbitrary rooms, be spawned, and be opened and closed.
• Grids that can carry a LUA data table, like entities do.

In order to implement these features and more like them, there are a lot of potential callbacks that would be useful, like a grid damage callback, a grid destruction callback, and a grid collision callback.

Currently, if you want to change how much damage an entity will take after an MC_ENTITY_TAKE_DMG callback, you either need to cancel the callback and send in a new one with the new damage value, send an additional damage callback to make up the difference, or handle the discrepancy in HP directly. It would be helpful to be able to change the damage amount directly from within the callback itself, perhaps via methods similar to those used for other callbacks such as MC_POST_GET_COLLECTIBLE or MC_PRE_ROOM_ENTITY_SPAWN.

If you go to the mod menu and enable or disable a mod that includes a shader, then immediately go and start a run, the game crashes. This does not occur when starting a run immediately after downloading such mods, and restarting the game after enabling/disabling mods sidesteps the issue.

A Sprite:GetCurrentAnimation() function would make life a lot easier as Sprite:IsPlaying() or Sprite:IsFinished() requires you to know which animations that specific entity can even play. This is especially troublesome when you need to work with entities of which you don't necessarily know which type they'll be, or if that entity in question has a lot of similar but differently named animations for which you need to check, resulting in a long chain of Sprite:IsPlaying() statements or a for loop checking for lots of different animations