Overlays

by Forum_account
Overlays
An easy way to manage and manipulate overlays.
ID:208499
 
BYOND's overlays are very useful but sometimes they're not easy to work with. It's easy to add an overlay to the player's list of overlays, but once you've done that it can be hard to update the overlay. It's easy to add overlays for the mob's shirt, shoes, pants, and hat, but it's not always easy to remove just their shoes overlay or change the icon state of their hat.

This library makes those things really easy. First, it provides the overlay() proc which is used to create overlays. The proc belongs to the atom, so you just call it for the mob you're adding an overlay to:

mob.overlay("hat")

That'll add an overlay whose icon matches the mob's icon and has the "hat" icon state.

This proc creates the overlay, adds it to the mob's list of overlays, and more importantly it returns an Overlay object. This object is defined by the library and is how you can easily manipulate overlays. Just keep a reference to this object and you can do some handy things, for example:

mob
var
Overlay/hat

Login()
..()
hat = overlay("hat")

// You can easily change the overlay's icon state
hat.IconState("silly hat")

// or hide it
hat.Hide()

// then show it again
hat.Show()

Version History

Version 7 (posted 06-09-2012)
  • Fixed a glitch with maptext on image objects. Every time you set the image's maptext it clears its maptext_width and height, so I made the Overlay object remember the values you set.
Version 6 (posted 05-25-2012)
  • Added the Overlay.Move() proc which moves the overlay to a new atom.
  • Got rid of the compile-time version checks to make the library work with pre-494 builds. If you don't have a version of BYOND that supports maptext, download it now!
Version 5 (posted 04-08-2012)
  • Added the RGB() proc to overlays. This proc sets an RGB value that's added to the overlay. The effects aren't cumulative. You can specify the args as a single string in the #RRGGBBAA form, or as three or four separate arguments (the separate RGBA components).
  • Changed the atom's overlay() proc to add a completely blank overlay (whose icon is null) if no parameters are specified.
  • Added the Overlay.MapText() proc as an alias of Text().
  • Updated demo\demo.dm to make use of the Text() proc.
  • Updated the maptext support to work with image-based overlays.
Version 4 (posted 03-25-2012)
  • Added the stat-bar-demo which shows how to create stat bars that use Overlay objects and manage how the overlay's icon_state is updated as values change.
  • Added the Overlay.Text() and Overlay.TextBounds() procs, which are used to set an overlay's maptext and maptext_width/height values. BYOND v494 is necessary to use maptext, but it currently doesn't work well with overlays (the overlay also shows an icon, even if you don't specify one).
  • Changed the atom.overlay() proc to support named arguments and added a layer parameter to it.
  • Changed how layering works for flicked overlays. When the overlays are created on the same layer as the mob, there may be issues. I recommend that you always specify a different layer for them.
Version 3 (posted 03-15-2012)
  • Added support for pixel offsets for flicked overlays.
Version 2 (posted 02-04-12)
  • Added support for overlays with exclusive viewers. This means you can create an overlay and control exactly who can see it. For example, you can create a health bar overlay and only make it visible to yourself so that other players can't see your health bar.
  • Use the Overlay object's ShowTo() proc to add an exclusive viewer to an overlay. Use the HideFrom() proc to remove an exclusive viewer. If the overlay has no exclusive viewers, it is shown to all players (you can also use the ShowToAll() proc to show it to everyone).
  • Added the "show-to-demo" which contains an example of how to create exclusive viewers. You won't be able to notice a difference unless you host the demo and connect another instance of Dream Seeker.
  • Added the "flick-demo" which contains an example of creating and animating two overlays. They can be animated independently or at the same time.
  • Fixed a bug where updating an overlay would cause it to become shown, even if you had called the overlay's Hide() proc.
Version 1 (posted 01-27-12)
  • Initial post
This library was basically taken straight from the Handy Stuff library so it's not really new (well, it's new to everyone who isn't familiar with that other library, which is most people). I added a little bit to it, but I figured I'd make a standalone library out of it. I've found that this feature is something I often use and it makes more sense to be able to include just this feature instead of including the entire Handy Stuff library.

Also, I think it'd be neat to have a library for every letter of the alphabet and O wasn't covered. H is already covered by HUD Groups so I could stand to get rid of Handy Stuff.
I just posted an update which lets you control who can see the overlays you've created. If you do this:

hat = overlay("hat")

The hat will be created as an overlay. If you do this:

hat.ShowTo(src)

The hat will be converted to an image object that's only visible to its owner. You can let more people see the hat by calling the ShowTo() proc again.

This all happens inside the library. You don't have to be aware of the images and overlays lists. It's all handled by the same /Overlay object and you use the same set of procs (ex: Icon, IconState, Layer, PixelX, PixelY, etc.) to modify it whether it's being handled internally as an overlay or image object.