itolib

Wondrous gizmos and gadgets for the restless mind.

A collection of wacky scripts I've written for projects I'm involved in, most prominently Bozoros and PlayZone.

Everything's kept fairly abstract so it can be generally applied for many use cases. Feel free to add this to your project to play around with, if anything catches your eye!

• NOTE: Expect a few breaking changes here and there (at least while everything is being polished), should you choose to add this as a dependency.

• NOTE 2: This is not intended to be a JLL replacement, though there are a couple overlapping features. It should be fine to use both in the same project without issues, but I'd still recommend opting for JLL's implementations for a more tried and tested approach.

Features (but here's the yapper)

A proper write-up and documentation for all components and their intended usage is planned, but here's a quick rundown of some of the more interesting ones:

• PlayerAttachable: An abstract effect or concept that continually affects a player (attach), and eventually stops (detach).
  • PlatformGrabbable: Physically attaches a player and makes them 'grab' on to a 'platform', making the player's position match said platform's until either a certain action stops being held (e.g. Jump), or they are detached through some other means. Used for Bozoros' balloon rides and PlayZone's slides.
  • PlayerLauncher: Launches any player who attaches, with heavily customizable trajectory parameters, and some additional optional features like fall damage prevention (until detached) and camera/player model tilting. Used for Bozoros' banana peels and PlayZone's trampolines.
  • MovementSensor: Checks if the attached player performs a specific movement action (e.g. Jump, Move, Crouch), and invokes an event callback if so. A cooldown can be applied so as to not trigger continuously, which can even be used for things like fake custom footstep sound effects. Used for PlayZone's ball pit movement effects.
  • PlayerHinderer: Slows down any player who attaches in a similar way to the vanilla spider web, up until the moment they detach. Has a field to allow the player to jump while hindered, even without stamina. Used for PlayZone's ball pit.
  • PlayerSeater: Makes any player who attaches enter the Cruiser sitting animation until detaching, without reparenting the player or having to use an InteractTrigger. Used for PlayZone's slides.
• DetectRegion: An abstract region within which to detect or perform (non-allocating) searches for overlapping Collider instances belonging to objects of a certain type.
  • PlayerSensor: Detects any players inside, entering, and/or exiting the region, with some additional event callbacks specifically filtering players that are alive.
  • EnemySensor: Detects any enemies inside, entering and/or exiting the region, with some additional filtering for whitelisting specific enemies, as well as requiring a certain amount of them before triggering events.
  • ScrapSensor: Detects any scrap inside, entering and/or exiting the region, with some additional functions for causing them to drop to the ground, or disable its MeshRenderer and/or Collider instances.
  • HazardSensor: Detects any objects in the MapHazards layer inside the region, with an additional function to despawn found hazards.
  • ExplodeEffect: Implementation of vanilla's Landmine.SpawnExplosion using DetectRegion, which performs non-allocating searches inside a Collider (instead of a radius), contains some additional customizability for explosion properties, and has an adjustable collision mask to define which layers should count as 'cover' from the explosion.
  • ConnectorMerger: Detects any instances of itself within the region, disables one of them and (optionally) moves the remaining one to the center. Has a priority system so certain connectors are preferred from others.
• ItemGrabbable: A GrabbableObject but with a bunch of event callbacks that can mimic an inheriting class (e.g. SoccerBallProp) without actually inheriting it, sacrificing polymorphism for modularity. All these components can be mixed and matched to create items with multiple properties (e.g. ItemKickable + ItemThrowable to make a throwable soccer ball).
  • ItemAudible: Mimics NoisemakerProp, with pretty much the same properties save for a few additional ones.
  • ItemKickable: Mimics SoccerBallProp, with some added customizability for kick trajectory parameters, event callbacks, and an adjustable collision mask for objects it can land on top of.
  • ItemThrowable: Mimics StunGrenadeItem, with some added customizability for throw trajectory parameters, event callbacks, and an adjustable collision mask for objects it can land on top of.
  • ItemWearable: Mimics BeltBagItem's wearable properties, specifically 'attaching' to either the player's head, belt, or a custom bone when pocketed.
  • ItemWhackable: Mimics Shovel, with added customizability for its properties (e.g. hit cooldown or hit speed), event callbacks for every stage of the 'whacking' process, and adjustable collision masks for hittable objects, with the added bonus of not allocating GC on every swing.
• Interactables: Components that inherit from InteractTrigger to fulfill various purposes.
  • InteractClimbable: An InteractTrigger for a ladder with adjustable climbing speed.
  • InteractLockable: A DoorLock implementation that allows custom tooltips that don't get overwritten when using a key. Doesn't inherit from InteractTrigger but is used alongside them for locked doors.
  • InteractPurchasable: An InteractTrigger that can spawn a prefab or run an event, but for a fee.
  • InteractSeatable: An InteractTrigger that acts like a Cruiser seat, but requiring a specific button press to get back up.
    • NOTE: Can be replaced with PlayerSeater + PlatformGrabbable for functionally the same effect, without the vanilla bug where two players get softlocked if they sit down at the same time.
  • InteractTalkable: An InteractTrigger that can transmit a player's voice over the Walkie while held; though only for one-way communication.
• Events:
  • DelayedEvent: An event that gets invoked after a given interval, either continuously or only once (until re-enabled).
  • WeightedEvent: Invokes an event (or several) from a specified list, each with its own weighted chance of being picked.
  • ScriptableEventListener: Can be used in combination with a ScriptableEvent to create an arbitrary 'global' event. This event can be raised from within any other event callback, to trigger something to happen on another, completely detached object.

There's a bunch more scripts that are very niche, require further explanation to employ, or are in need of some refactoring (as they're a bit old now). If you're curious about any of them and/or have any questions regarding usage of a particular script, I've kept my commit messages fairly lengthy when adding new scripts, but also feel free to ping me in the Lethal Company Modding Discord server. Feedback, suggestions, and bug reports are also welcome!

Credits

• The LC Modding Community — For support, ideas, encouragement, and just good vibes in general.
• LethalMatt — For Bozoros, my all-time favorite moon (I am not biased at all...), but also for coming up with wacky concepts for PlayZone that necessitated additional scripting functionality, which was then added to this library.
• IAmBatby — For LethalLevelLoader, the backbone for a significant chunk of custom content for this game. A couple scripts in here also require it or make use of its features.
• PF1MIL — For Early Access™ testing of various scripts, suggesting additions and improvements, and just generally waiting patiently for this library to release.
• You! —

Changelog

[v0.3.2]

Small fix for NetworkedHittable, added LayerMask fields to a couple scripts.

• Fixed NetworkedHittable objects erroring out when hit by a non-player.
• Added a LayerMask field to both SpraySensor and FearInducer, which determine the layers that should block the player's line of sight.

[v0.3.1]

Couple small improvements and fixes.

• Added ISeededScript interface, for scripts that need randomization using the current map seed.
  • Only used for ScrapSpawner at the moment, still thinking about a few things with its implementation.
• Made ScrapSpawner's respectSingleItemDay field actually work, and made its seededRandom field affect a couple things I missed.
• Added default curves for ItemKickable and ItemThrowable that correspond with the Soccer ball and Stun grenade curves, respectively.
• Made ItemTargetable's fall curve override be reset upon being picked up, so items don't act weird when normally dropped.
• Switched to using an AABB check of the local player for PlayerSensor, if the onlyAffectsLocalPlayer field is enabled.
  • Most likely will end up switching to AABB checks for all players at some point, instead of overlap stuff.
• Fixed DetectRegion scripts sometimes 'remembering' objects that had been previously found, but are no longer present.

[v0.3.0]

Did a couple changes, I think...

• Added SpraySensor, for detecting if an object is being sprayed with Spray Paint, Weed Killer, or any other item that uses or inherits SprayPaintItem.
  • Multiple spray 'treshholds' can be defined, each with event callbacks, to have stuff happen depending on the number of times sprayed (e.g. to have something happen after 3 sprays specifically).
  • Does not actually hook into any SprayPaintItem code, so it should be compatible with anything that modifies it (e.g. BetterSprayPaint).
• Added FearInducer, which increases a player's fear level and plays the fear effect when looked at.
  • Has some customizability for things like range, angle, and amount of fear to instill upon the player depending on how close they are.
  • Disables itself after triggering once, but can be re-enabled to give the player another spook.
• Added ItemDiscardable, for items that drop themselves from the player's inventory.
  • Has a function to cause the item to drop itself from the player's inventory (even while pocketed), as well as a despawn timer after getting discarded.
• Added EventfulApparatus, a LungProp-inheriting object with a bunch of events similar to ItemGrabbable.
  • (PlayZone) TwinApparatus now inherits from EventfulApparatus.
• Added MultiAnimationEvent, which is similar to PlayAudioAnimationEvent but without a few features that can be done in a better way with other components (e.g. with NetworkedSource), and with a list of event callbacks to execute instead of the single OnAnimationEvent.
• Added AudioGroup, which checks objects and their children for any AudioSource, and allows some basic audio functions to be run on all sources at once.
• Added CeilingAdjuster, which just raises whichever object it's attached to to the highest point in the dungeon + a specified additional offset.
• Added DungeonConditional, for doing stuff whenever specific interiors generate.
• Added lerping to PlayerLauncher, so it smoothly ramps up towards the applied force instead of immediately applying it.
  • Ramping speed is adjustable, and it comes with a new detach condition for once the force is fully applied.
  • Also fixed the unintended rocket jump whenever players jump right before touching the PlayerLauncher, but it can be turned back on!
• Added lerping to PlatformGrabbable, to smoothly move the player towards the center of the platform, instead of teleporting them to it.
  • Not teleporting instantly means the player will be slightly behind the intended position, but this grabbing speed can be adjusted.
• Added IEventfulItem interface, which includes every event available in ItemGrabbable.
  • Made all modular item scripts (e.g. ItemWhackable) require using items that implement the IEventfulItem interface.
  • Made ItemGrabbable and EventfulApparatus implement IEventfulItem, so they're both compatible with all modular item scripts!
• Added abstract ItemTargetable, which represents items that follow a trajectory towards a set destination.
  • ItemKickable and ItemThrowable now both inherit from it, and thus share some common functionality.
  • Both ItemKickable and ItemThrowable had some revisions done to their trajectory logic, too.
• Added IWeightedScript interface, which includes a bunch of default method implementations to handle weighted randomization.
  • WeightedEvent and ScrapSpawner now implement said interface.
• Added generics to the IPooledObject interface.
  • Now the abstract PooledObject contains Unity-related object pooling stuff, and AttachedEffect inherits from it.
  • It also now actually supports creating a given number of instances to have ready from the start.
• Overhauled ScrapSpawner a bit (using the IWeightedScript interface):
  • Added a weighted list of items to spawn, instead of just a single item.
    • Blank references (even for modded items!) should be working correctly, too.
  • Added field to ScrapSpawner to allow it to use the current moon's spawn weights, instead of specifying a list.
    • Overrides any items set in the weighted list.
  • Added a minimum and maximum set amount of items to spawn, instead of simply spawning one at every defined location.
  • Added able to spawn scrap at a random location within specified area bounds, instead of only at set points.
  • Made spawned scrap actually count towards the current round's total scrap value amount.
• Added pretty much all ItemAudible fields to NetworkedSource, and improved its networking a bit.
  • NetworkedSource now has functionality to, for instance, alert nearby enemies or play sounds over the walkie.
• Made MaterialSwapper able to do a set amount of swaps per activation, instead of doing all of them at once.
  • Allows for 'cycling' through various material states by only doing a certain number at a time.
• Improved enemy filtering for EnemySensor.
  • Added callback events for individual filters, as well as enemy blacklisting.
• Added GrabbableObject attaching to AttachedEffect.
  • Switched AttachedEffect generic type to Collider, and made it detach upon disabling.
• Added a sitting animation field to PlayerSeater, to be able to use the sofa and electric chair sitting animations, too.
• Added a stamina requirement field for triggering MovementSensor events.
• Added a player stamina draining function to PlayerHinderer.
• Added field to mute quicksand sinking sounds for PlayerHinderer.
• Added a networked onLogCollected event callback to DungeonStoryLog.
• Made DetectRegion scripts take (lossy) scale into account when performing searches.
• Made InteractClimbable's specialCharacterAnimation field automatically disable itself, if twoHandedItemAllowed is enabled.
  • Allows players to climb with two-handed items.
• Merged WallBreaker script into ConnectorMerger, which can now be used to disable either connector, or both.
• Fixed PlayerSensor player search counting players twice.
• Fixed ExplodeEffect explosion spawning a fair distance away from where it was actually supposed to.
  • Also fixed its spawnExplosionEffect field not actually doing anything.
• Fixed all BaseConditional scripts not applying on dungeon completion.
• Fixed PrefabSpawner not working without the spawner itself being spawned.
  • But who spawns the spawner?
• Fixed NetworkedHittable not actually serializing hitID and the player who hit when sending hit information to other clients.
• Fixed sun not actually being hidden by the SunScreen script.
  • Switching spectating camera also no longer toggles the sun, but I don't think it was even working in the first place...
• Fixed detachTimer field for PlayerAttachable not actually starting when manually attaching the player (instead of with attachOnEnter).

[v0.2.0]

Did some pretty substantial refactoring; added and fixed a couple things, too.

• Added some stuff to ExplodeEffect:
  • Made ExplodeEffect able to target any object that implements the IHittable interface.
  • Added separate enemy and IHittable curves to ExplodeEffect, to deal specific damage to non-player targets.
  • Replaced damageRange and killRange with damageBounds and killBounds, for visualization purposes.
• Added player sinking curve overriding to PlayerHinderer, to control how deep the player actually sinks before dying.
• Added OutOfBoundsAdjuster, which just moves the current moon's OutOfBoundsTrigger to the lowest point in the dungeon + a specified additional offset.
  • Intended for more vertically-oriented dungeons.
• Made DetectRegion actually take region rotation into account when performing searches.
• Did a lot of refactoring under the hood, based on IAmBatby's suggestions and feedback!
  • Made scripts with update loops disable themselves when not in use, the most important one being PlayerAttachable.
  • Removed all uses of null propagation on UnityObject stuff, fixing some rare NullReferenceException errors.
  • Switched from using NetworkObjectReferences to NetworkBehaviourReferences when networking stuff, thus skipping a step.
  • Some other miscellaneous tweaks and fixes here and there.

[v0.1.4]

Reworked PlayerLauncher a bit, fixed WeatherRegistry compatibility.

• PlayerLauncher now uses a list of forces to apply to the player, to combine multiple sources of rotation (e.g. where the launcher is facing + where the player's looking towards).
• Added some drowning/quicksand-related stuff to PlayerHinderer, but it's not quite working just yet...
• Fixed WeatherConditional compatibility with WeatherRegistry, I forgor to actually apply my patch for it...

[v0.1.3]

Added player callbacks to NetworkedHittable, fixed some stuff with WeightedEvent.

• Added information to NetworkedHittable about the player that performed the hit, as well as some separate hit event callbacks with said player given as an invoke parameter.
• WeightedEvent rolls should now actually roll when initiated by clients.

[v0.1.2]

Added DamageHittable and ToggleEvent, fixed some stuff with scrap-related scripts.

• DamageHittable is a NetworkedHittable with health, it's got a list of conditions with event callbacks that are invoked when its health falls to or below specified numbers.
• ToggleEvent is just a behaviour with event callbacks for OnEnable() and OnDisable()... there ain't much more to it, I just needed it for something.
• ScrapSpawner should actually sync scrap position now, I forgor to add it...
• ScrapTeleporter now uses a seeded Random instance, takes teleport area colliders' center point into account, and should properly set item rotations if set to activate on scrap spawn (as it was supposed to have been doing).

[0.1.1]

Added some compatibility for PizzaTowerEscapeMusic.

• Pulling only one TwinApparatus will no longer trigger escape music.

[0.1.0]

Initial release!

• Documentation is lacking for most scripts and there's a good amount of jank, but it should be stable enough for a release.
• Proper documentation and wiki pages for all features is planned, alongside some example prefabs used in Bozoros and PlayZone.