DOCSEARCHbyAlgolia
Submit Docs

IsaacScript Common Documentation

website·Indexed 30 days ago

https://isaacscript.github.io/

API reference for the isaacscript-common package, providing classes, functions, and types for modding. Includes utilities for player health, item pool detection, custom stages, room transitions, and grid entity management, as well as specialized features like DebugDisplay and ModdedElementSets.

Tokens
170.3K
Snippets
1.4K
Records
1.8K
Agent score
75%

What's inside IsaacScript

  2. Overview of ExtraConsoleCommands feature

    The ExtraConsoleCommands class (extending Feature) adds a set of custom commands to the in-game console. To use this feature, a mod must be upgraded with ISCFeature.EXTRA_CONSOLE_COMMANDS.

    Conflict Handling: If multiple mods enable this feature, the first loaded mod controls the command logic. A global variable __ISAACSCRIPT_COMMON_EXTRA_CONSOLE_COMMANDS_FEATURE is created to allow non-main instances to function. If standard library commands fail in a multi-mod environment, ensure all mods are using the latest version of isaacscript-common.

  3. Overview of IsaacScript for The Binding of Isaac: Repentance

    IsaacScript is a framework that enables the development of mods for The Binding of Isaac: Repentance using TypeScript. It functions as a compiler that automatically converts TypeScript code into Lua, allowing developers to use modern language constructs and strong typing while maintaining compatibility with the game's Lua-based modding system.

  4. Overview of IsaacScript for Binding of Isaac Repentance

    IsaacScript is a framework that enables the development of mods for The Binding of Isaac: Repentance using TypeScript instead of Lua. It provides a more modern development experience while targeting the game's Lua environment.

  5. Overview of isaac-typescript-definitions

    The isaac-typescript-definitions package provides TypeScript definitions for the vanilla Isaac Lua API. It includes standard API definitions as well as community-contributed bugfixes and quality-of-life improvements not yet present in the official API. In a TypeScript mod, Isaac API classes (such as Entity or Isaac) are used identically to how they are used in Lua mods.

  6. Use ModdedElementSets to manage collectible and trinket types

    The ModdedElementSets class provides cached arrays and sets of both vanilla and modded game elements. To use any of the methods in this class, you must upgrade your mod with ISCFeature.MODDED_ELEMENT_SETS.

    Important Constraint: These functions can only be called after at least one callback has been executed. This ensures that all collectible and trinket types from other mods are present, regardless of mod load order.

  7. Log specific entities or grid entities

    IsaacScript provides helper functions to log information about specific entity objects or arrays of entities.
    // Log a single entity
logEntity(this, entity);

// Log an array of entities
logEntities(this, entities);

// Log a single grid entity
logGridEntity(this, gridEntity);

// Log an array of grid entities
logGridEntities(this, gridEntities);

  8. Understand TearVariant and TearFlag differences

    In the Isaac engine, TearVariant primarily controls the graphical appearance of a tear, whereas TearFlag controls the gameplay mechanics. For example, a needle tear uses TearVariant.NEEDLE for its visual look and TearFlag.NEEDLE for its exploding behavior.

    There are notable exceptions where the variant also grants gameplay properties:

    • TearVariant.CHAOS_CARD (9): Grants the instant-kill property.
    • TearVariant.KEY_BLOOD (44): Grants both the graphical effect and extra damage (associated with Sharp Key).

  9. Use ModdedElementDetection to identify modded game elements

    The ModdedElementDetection class (extending Feature) allows developers to determine the range and count of modded collectibles, trinkets, and cards.

    Critical Constraints:

    1. Feature Upgrade: You must upgrade your mod with ISCFeature.MODDED_ELEMENT_DETECTION to use these methods.
    2. Timing: These functions can only be called after at least one callback has been executed. Calling them in the menu before any callbacks occur will throw a runtime error, as the full list of modded elements is not known until all mods have loaded.

  12. Understand the IsaacScript project directory structure

    When running isaacscript init, a project structure is created. The root directory (named after your mod) contains the following key directories:

    • src/: Contains TypeScript source code (e.g., main.ts).
    • mod/: The source mod directory. Files placed here are automatically mirrored to the game's mods folder.
    • node_modules/: Contains project dependencies (TypeScript, TypeScriptToLua, etc.). This is generated via npm install and should be ignored/excluded from Git.
    • .vscode/: Contains recommended settings for VS Code.
    • .github/workflows/: Contains CI configuration for GitHub Actions.
    project/
├── src/
│   └── main.ts
└── mod/
    ├── main.lua
    └── metadata.xml