ID:1895493
 
There are places where the reference could use a little TLC. Things might be worded a little better than they are, and some more (small!) inline images wouldn't go amiss. To that end, I'd like to invite folks to post proposed reference changes here.

Rules:

1) For any section of the reference you change, please post the exact type path, the lines you removed, and the lines you added. They should be inside DM tags. This will make it easy for me to find and replace the old text.

2) KISS. Less text is better, as long as it's clear.

3) If you want to provide a new image to use, you don't have to inline it yourself. I can handle that part if I like the image. Just point the <img> tag to the image's location, and include the image in the thread. (It's actually better if I handle the optimization and inlining myself, as I can shrink the image using AdvPNG and pngout for best results. But if you want to try using those as well, by all means.) I want to keep images super small wherever possible.

4) The few images that are present use Trebuchet MS as the font. This would be preferred for consistency.
Should probably sticky this
A couple of years back, the website had a "dynamic" reference that allowed moderators to add comments to entries. Do you still have the data for that? I don't remember how many comments were actually added (I think Garthor wrote most of them), but it might be a good starting point for the community to spruce some of them up and integrate them more directly into the body text.
The locate proc currently lists three examples although I think it could use one more.

Current Example 1
var/mob/shopkeeper/M = locate()
if(M)
usr << "Found the shopkeeper."
else
usr << "Could not find the shopkeeper."

This looks for a mob of a type /mob/shopkeeper in the world (world.contents).

Current Example 2
usr.Move(locate(/turf/Home))

This "teleports" the usr to a turf of the type /turf/Home.

Current Example 3
usr.Move(locate(1,2,3))

This moves the usr to the turf at coordinates (x,y,z) = (1,2,3).

Proposed Example
var/obj/apple/A = locate(/obj/apple) in usr.contents
del(A)
usr << "You eat an apple from your backpack."

This narrows down the search area to usr.contents only instead of searching through the whole world.
In response to DarkCampainger
DarkCampainger wrote:
A couple of years back, the website had a "dynamic" reference that allowed moderators to add comments to entries. Do you still have the data for that? I don't remember how many comments were actually added (I think Garthor wrote most of them), but it might be a good starting point for the community to spruce some of them up and integrate them more directly into the body text.

The underlying posts that were created should still exist (and the comments with them), and the conversion tool should still work. The problem is, the old reference thing was really never updated to work with our new forum setup and requires a major refurb, so it's been back-burnered.
In response to Zecronious
Hmm. 3 examples seems like it's probably enough, though. The tag and ref forms of locate() aren't given examples either, so this would probably be overkill.
In response to Lummox JR
How can you have too many examples? Heck I didn't know what tag was for 5 years until someone mentioned you could use it with locate.

I still have no idea what /ref is and I've never seen it used.
The section on overlays is correct, but incredibly misleading.

This is a list of icons which are displayed on top of the object's main icon.

The individual items in the list may not be directly accessed, since they are stored in a special internal format. However, the list operators +=, -=, and the procedures Add, Remove, and Cut work normally.

The overlays/underlays list is absolutely not a list of icons, nor is the list inaccessible.

Proposed change:

"This is a list of appearances, which are displayed on top of the main object's appearance.

The invidivudal items in this list can be directly accessed, though it will not reflect exactly what was added. See appearances for further details. All list operators can be used with this list, but be aware that Find() and Copy() will use and return appearance objects rather than the values added initially.

When a data type is added to this list, it is converted to an appearance internally. Data types that may be used as overlays are icons, icon states (text strings), atoms, and atom types. If the appearance of an atom is changed between addition and removal, the intended appearance may not actually be removed. This is because when an atom is used as an overlay, the appearance represents a static "snapshot" of the atom. Future changes to the atom will not change the overlay appearance."


Same goes for underlay, but you know, with words.
In response to Zecronious
Zecronious wrote:
How can you have too many examples? Heck I didn't know what tag was for 5 years until someone mentioned you could use it with locate.

I still have no idea what /ref is and I've never seen it used.

\ref is a text macro that allows you to get the internal id of an object. Every datum, list, client, appearance, sound, matrix, icon, savefile, etc. currently created in the world has a unique reference id. This can be used as a sort of "weak" reference to refer to an object, though it's traditionally used to determine the object that will receive Topic() calls when clicking on a link in a browser or in output.
In response to Ter13
Going along with that, maybe it'd make sense to have a special note on appearances.
I think atom.appearance var covers the subject nicely. Maybe we could clip the entire article for atom.appearance into an appearance article like so:

Every atom or image has an appearance, which controls all of the values relating to how it appears on the map. (The overlays and underlays lists are lists of appearances.)

+ Appearances contain all of the following values:

alpha
blend_mode
color
desc
density
dir
gender
icon
icon_state
invisibility
infra_luminosity
layer
luminosity
maptext
maptext_width
maptext_height
maptext_x
maptext_y
mouse_over_pointer
mouse_drag_pointer
mouse_drop_pointer
mouse_drop_zone var
mouse_opacity var
name
opacity
overlays
override (images only)
pixel_x
pixel_y
pixel_z
screen_loc
suffix
text
transform
underlays
verbs

+ Any changes to the above variables for an atom or image will cause the engine to check for a matching appearance. If it exists, the atom's appearance will change to that existing appearance. If it does not exist, a new appearance will be created instead. Only one identical appearance will exist for each unique combination of these values. When an appearance no longer is associated to any atoms or overlays, it will be removed. The maximum number of unique appearances at runtime is X.
The .. proc reference is currently incomplete.

Suggested addition:

+ ..() will search for the last defined override for the current type's proc in the project. If none is found, it will search backward up the heirarchy up to the first definition of the proc. This should be avoided where at all possible because it incurs extra overhead. The only cases where multiple overrides of the same proc should be used are in the case of making self-contained libraries that do not interfere with existing code.
In response to Ter13
I made a change to ..() along those lines. This is what I added, right before the paragraph "..() can also be used for predefined procs":

If O overrides the same proc more than once, ..() will search for the previous version and use that. For instance, you could have two O.history() procs; the second overrides the first, but the original could still be called via ..(). The original in turn could call ..() to reach P.history(). Overriding the same proc more than once in the same type should be avoided wherever possible, because it incurs extra overhead, it makes the code harder to read, and it isn't always clear which one gets called first. (Usually, the only time you'll want this to happen is when using libraries.)
The reference completely neglects any mention of UP/DOWN in the get_step, step and walk functions as a possible bit flag for the dir argument. (actually, the reference completely forgoes the explanation that directions are bitflags in DM)
This behavior for initial should be documented:
http://www.byond.com/forum/?post=137997#comment11700565
The Red Book has some undocumented stuff that might as well be officially documented.

I think it'd also be smart to offer a guideline for code conventions (although that page is currently just a description of the naming conventions found in the Reference).
In the entry for 'cache', it mentions:
"It is also possible to include additional supplementary .rsc files by using the #include statement. "

It might be a good idea to add this to the entry for the include directive. This was added back in version 230:

You may now include entire resource cache archives. This might be useful in library code that has its own resource files. Instead of distributing all the individual resource files (and having to worry about the directory where the user installs them), you can just compile your library and distribute the source code along with the .rsc file. The user can then simply include your .dm and .rsc files (or you could include the .rsc file yourself), eg:
  #include "mudlib.rsc"
turf/icon = 'glob.dmi' //this could be a file that exists in mudlib.rsc

Whoah whoah whoah...

Does this mean entire .rsc files can be included in a project?

Does this merely merge the two rscs into one, or does this actually allow you to share resource pools with another game making it so that you don't have to download the exact same rsc twice if two games share it?

EDIT: THIS CHANGES EVERYTHING.

Obligatory:
In response to Ter13
Ter13 wrote:
Whoah whoah whoah...

Does this mean entire .rsc files can be included in a project?

Yeah, you can literally pre-compile a rsc and distribute it in a project. Or compiling projects with different themes...something. Fast changing of mass resources.

Like, imagine if people made 'mapper packages' (for mappers who don't need to see much code) WITHOUT SHARING ANY ICONS!
Does this merely merge the two rscs into one, or does this actually allow you to share resource pools with another game making it so that you don't have to download the exact same rsc twice if two games share it?

Technically, this shouldn't be happening either way? I thought BYOND did some checking in terms of not downloading the same files across worlds.

This is what we did with Eternia's map maker, we included the Eternia.rsc but not the actual dmi files. The first time you compile you'll get a warning about the file only existing in the rsc, but it'll go away in subsequent compiles that session.
Page: 1 2 3 4