BigAtom Overlay Mode

Worried about large mob counts with BigAtom? Want to avoid the occasional image breakup that happens with SYNC_STEPS? Overlay mode in the BigAtom library removes these issues entirely. This article will explain how to use overlay mode and the advantages it has over the default mode.

If all you want is a simple multi-tile display, without any special targeting of collision considerations, you should check the "BigAtom - Keep It Simple, Shadowdarke" article. It's a very short read and gets you running with a single line of code.

This article builds on the information in "Go BIG in Existing Games". That article covers all the basic BigAtom concepts, in particular how to change your existing code to work with BigAtoms properly. If you haven't read that article, you should probably do so before continuing with this one.

Table of Contents

  1. Overlay Overview
  2. Setting Overlay Mode
  3. Checking For Overlay Mode
  4. Less Is More
  5. Conclusion

Overlay Overview

BigAtom's Overlay mode builds the atom's display out of overlays placed on the bigatom_src, instead of using icons on each sub part of the BigAtom. There are two major advantages and three disadvantages to overlay made in BigAtom:


  1. The display never breaks up as it sometimes does in No Overlay Mode. (Unless you extend the pixel offsets too far. See Disadvantage 1 below.)
  2. You can cull unneeded atoms from the BigAtom's parts list, freeing up resources and making the library perform faster. I'll cover this in more detail below in Less Is More.


  1. Overlay mode only works for BigAtoms that are 7 tiles or less wide and high. If the BigAtom is too large, it will automatically switch to No Overlay Mode. Technically BYOND can handle larger offsets, but you will see the icon tear if the overlay + atom + movement offsets go outside of the range from -128 to 127. If you plan to make use of pixel_x and pixel_y you may want to limit your bigatoms to an even smaller size.
  2. Overlay mode BigAtoms will not display on the map until the bigatom_src is within one tile of the displayed map space. This means that very large overlay mode BigAtoms might already be one or two tiles onto the edge of the map before a player sees them.
  3. At the time of this writing (BYOND 412.977), Overlay mode BigAtoms do not flick() properly. Hopefully this will be fixed in the BYOND client in the near future.

Setting Overlay Mode

Setting overlay mode is simple. All you have to do is remove the BIGATOM_NOOVERLAYS flag from the atom's bigatom_mode var. If that leaves no flags, be sure to add BIGATOM_ON to bigatom_mode so the library still knows to use BigAtoms. There are also several specialized bigatom_mode flags for automatically culling parts. They're covered below in Less Is More.
If the code was... Overlay Mode Equivelent
mob bigatom_mode=BIGATOM_NOOVERLAYS
mob bigatom_mode=BIGATOM_ON
obj bigatom_mode=BIGATOM_MAYMOVENULL

If you want to change to OverlayMode at runtime, you need to remove the BIGATOM_NOOVERLAYS flag, then call the bigatom_src's bigatom_Icon() proc to rebuild the display.

mob verb/switch_to_overlay_mode() if(bigatom_src && bigatom_src != src) src = bigatom_src bigatom_mode &= ~BIGATOM_NOOVERLAYS bigatom_Icon()

Checking For Overlay Mode

As noted in the disadvantages, very large BigAtoms will automatically turn off overlay mode. If you want to double check to be certain a specific BigAtom is in overlay mode, just check the BIGATOM_NOOVERLAYS flag in the bigatom_mode var.

For example:

mob/New() . = ..() if(bigatom_mode) if(bigatom_mode&BIGATOM_NOOVERLAYS) world << "[src] is a BigAtom without overlay mode." else world << "[src] is an overlay mode BigAtom." else world << "[src] is a single atom."

Less Is More

The primary advantage of overlay mode is that you can enjoy all the features of BigAtom with a fraction of the atoms. A 7x7 tile BigAtom takes 49 atoms to display without overlay mode! Each time that atom moves, it will have to loop through all 49 of those atoms to make sure they can each move. If your game is very large, you may also run afoul the atom limits. Overlay mode can display a 7x7 bigatom with only 1 atom, and can provide additional features with just a handful more.

You can delete any of the sub-parts of an Overlay Mode BigAtom. The sub-parts are only required to help with things like targeting, density checks, and tracking when a mob enters or exits a turf or area. If you aren't worried about these things you can delete all the sub-parts and use only the single bigatom_src, which is the core atom.

Even if you do want the extra BigAtom features, we don't need every sub-part to provide the features. For targeting and simple enter()/exit() tracking, you can make due with just the corner parts (for a total of 5 atoms per BigAtom). For detailed density tracking, you will want to at least have every sub-part along the edges of the dense region. There is one important pitfall to remember if you are using a hollow region for density. It is possible that a small dense atom could get inside the hollow. If that happens, the BigAtom and the atom inside the hollow will probably be unable to move.

If you know ahead of time which sub-parts of the BigAtom you want to keep, you can use special bigatom_mode flags to automatically generate only the sub-parts you want:

No subparts are created. (A single tile atom with a larger icon attached, but no targeting or collision benefits.)
Only the corners are created. (At most 5 atoms per BigAtom, very limitted targeting and collision detection.)
Parts at the north edge are created.
Parts at the south edge are created.
Parts at the east edge are created.
Parts at the west edge are created.
Parts are created around all the edges. (Only saves atoms if the BigAtom is larger than 3x3 tiles. Provides pretty accurate targeting and collision detection, but you have to be careful that it doesn't get a smaller atom stuck inside the edges.)
You may combine BIGATOM_PARTS flags by ORing them together with the | operator. For instance, if you only want the bottom edge and the other corners, you can use
If no BIGATOM_PARTS flags are set, all the sub-parts will be generated.

If you want to generate a pattern that you can't produce with BIGATOM_PARTS flags, you can delete any sub-parts you wish after the display is generated by the bigatom_Icon() proc.

For example:
mob/bigatom_Icon() // override bigatom_Icon() so this happens every time the display is generated . = ..() // do everything that the bigatom_Icon() proc normally does if(bigatom_parts && !(bigatom_mode&BIGATOM_NOOVERLAYS)) // if this is multi-tile and overlay mode // insert custom part deletion code here

If you use a particular pattern often and think it would make a good general purpose addition to the library, by all means let me know on my forum and I may add a new flag to the library in your honor. :)


Overlay mode can greatly improve the performance of the BigAtom library, if you are willing to accept the few limitations that come with it. If you've had any trouble with sluggishness or encountered the various atom limits using the BigAtom library in your project, you should definitely try overlay mode and cut out as many unneeded parts as possible from each BigAtom.

If you have any problems or need clarification please leave a post on my forum.

~ Shadowdarke