ID:136307
 
I wanted to keep talking about libraries but from another angle, so here's a new thread.

There are many libraries on the hub, and I suspect some aren't very user-friendly, or maybe difficult to implement. I think we need a good article and guidelines how to create a library that people can use without hassle. Some kind of standard, to avoid conflicts between different libs as well.

Anyone up for it?

/Gazoot
Gazoot wrote:
There are many libraries on the hub, and I suspect some aren't very user-friendly, or maybe difficult to implement. I think we need a good article and guidelines how to create a library that people can use without hassle. Some kind of standard, to avoid conflicts between different libs as well.

Anyone up for it?

I'm pretty sure Deadron has been planning something like this. But he's also busier than a one-armed paperhanger, so there's no telling when he'll get to it!
In response to Gughunter (#1)
My concepts of good reliable libraries comes from my understanding of re-useable functions and objects. A library should be as easy to use as these common programming elements. Even if I have the source code available to me, I should have to know the inner workings necessarily to make the library useful to me.

I would love to see libraries that follow some sort of standard, so that implementation is as quick and painless as possible. And there should be adequate documentation about the libraries abilities, and a few examples to show how to get these abilites to work.

The SwapMaps library article that Lummox wrote for digitalBYOND back in late 2002 is an excellent example of the type of library documentation I would like to see more often.

Done properly, even OneFishDown's desire to compile libraries can be met with success, if standardized and documented.
Gazoot wrote:
I wanted to keep talking about libraries but from another angle, so here's a new thread.

There are many libraries on the hub, and I suspect some aren't very user-friendly, or maybe difficult to implement. I think we need a good article and guidelines how to create a library that people can use without hassle. Some kind of standard, to avoid conflicts between different libs as well.

The standards I go by:

  • Name all global vars and procs, or vars and procs modifying an existing datum (like obj) with a library-specific name, like for example, SwapMaps_Load(). Customized datums shouldn't have to follow this rule.
  • Document every external var and proc (that is, anything that's made available to a user). Everything else treat as internal; use comments to explain that it shouldn't be used directly.
  • Plan for flexibility: Include options for various ways of using the library. Allow for overridable procs if you want the library behavior to be user-extensible.

    SwapMaps was my first attempt at a library, and I hope I did well to make it libraryish. Too many programmers think of libraries as just another piece of code, but they really have to be thought of as being able to conflict with each other.

    In a lot of ways I followed the naming convention guideline based on what I've seen in other libraries (non-BYOND) and in Deadron's work. He's more familiar than I am with the methodology behind putting something like this together.

    Lummox JR
In response to Lummox JR (#3)
Lummox JR wrote:
In a lot of ways I followed the naming convention guideline based on what I've seen in other libraries (non-BYOND) and in Deadron's work. He's more familiar than I am with the methodology behind putting something like this together.

You got all the important rules. The rest is mostly a matter of getting a feel for how to factor and make things flexible, which is mostly a matter of experience and iteration.

I guess one addition I'd mention is that you want flexibility for overriding things or you won't help the power programmers, but (what I didn't do with my first libraries) you want to boil it down to one or two calls for the 80% cases, or most people won't use your library. That realization is how pathfinding went from instantiating and calling a pathfinding object to simply calling dd_StepTowards(). For CharacterHandling, if you only want one character/player, I'm proud that there are actually no calls: all you do is include the library, and you magically get character/location saving.

I did intend to do an article on libraries, but it's not on my short-term list right now, so if anyone else wishes to they should feel free.
In response to Deadron (#4)
I guess one addition I'd mention is that you want flexibility for overriding things or you won't help the power programmers, but (what I didn't do with my first libraries) you want to boil it down to one or two calls for the 80% cases, or most people won't use your library. That realization is how pathfinding went from instantiating and calling a pathfinding object to simply calling dd_StepTowards(). For CharacterHandling, if you only want one character/player, I'm proud that there are actually no calls: all you do is include the library, and you magically get character/location saving.

I can relate to this -- for s_admin 3.0, I've been planning on moving away from the "pre-existing-verbs" system and just providing a series of procedures under the s_admin datum to do the work. A separate Spuzzum.s_admin.Verbs library acts as a standard set of accessor functions, but it is not necessary; programmers who like to get dirty can override any of the procedures, or can write their own accessor routines. People who want to use s_admin without knowing what's behind the scenes can simply install the s_admin.Verbs library and use s_admin straight from the box, no assembly required -- all they need to do is find some way to register themselves as a GM, and I'm including a couple demos for that purpose (one of which determines if there are no Master GMs, and if there aren't, makes the first player who logged into the game one, and never adds another one automatically).

Yeah, yeah, I know, less hyping and more typing... but I usually don't hype something unless I'm either A) not working on it but wanting to, or B) getting distracted from the project and attempting to return inspiration to myself. (In this case, it's the former.)
In response to Lummox JR (#3)
What swapmaps lacked was ways to use it in games. Like a battle map, or just a random area that you can specify where you want this and that with this located. And a preset map loading
In response to Sariat (#6)
Sariat wrote:
What swapmaps lacked was ways to use it in games. Like a battle map, or just a random area that you can specify where you want this and that with this located. And a preset map loading

I don't know why it couldn't do those things. I've been playing around with the library and it's worked perfectly fine for generating and destroying segments of space as the players enter and exit them. I'm sure it's not much different for setting up battle maps and I think it handles it's own way of saving/loading maps. But I haven't tested out the saving/loading since in my game speed is very crucial for generating and destroying maps because it needs to happin very often.
In response to Spuzzum (#5)
Here's some inspiration.

I don't know about anyone else, but I am eagerly looking forward to s_admin 3.0. I currently have s_admin and a few 'modified' versions of it built to fit various needs. One of which includes turning the verbs into procs, just like you had mentioned.

In short, WHEN WILL IT BE OUT?!?!?!?!?!?!?! =P

Sorry, got carried away. Seriously though, I'm really looking forward to it.

-<font color = #0000FF>Sapphiremagus</font>
In response to sapphiremagus (#8)
As am I. And if I may add, WHEN WILL IT BE OUT?!?!?!
In response to Lummox JR (#3)
Lummox JR wrote:
SwapMaps was my first attempt at a library, and I hope I did well to make it libraryish. Too many programmers think of libraries as just another piece of code, but they really have to be thought of as being able to conflict with each other.

Exactly! And a big thanks for creating SwapMaps, now I can stop worrying about Dmpmaker, which was terribly outdated. Dmpmaker created maps in the real .dmp format, however. Maybe something for SwapMaps 2.0?


/Gazoot
In response to Sariat (#6)
Sariat wrote:
What swapmaps lacked was ways to use it in games. Like a battle map, or just a random area that you can specify where you want this and that with this located. And a preset map loading

I'm not sure I follow you. I specifically planned for battle maps with the SwapMaps_CreateFromTemplate() proc. One swapmap can be replicated ad infinitum. All that's necessary is for the author to create the battle map templates first, and save them as swapmaps.

The "just a random area that you can specify where you want this and that with this located" I don't get either. You can create a random area of any size you want, and fill it with anything you want, with the library's existing functionality.

The only thing the library doesn't handle is chunks, whereby you load a swapmap into a specific place (even into another swapmap). However I'm working on an update that addresses this.

Lummox JR
In response to Gazoot (#10)
Gazoot wrote:
Exactly! And a big thanks for creating SwapMaps, now I can stop worrying about Dmpmaker, which was terribly outdated. Dmpmaker created maps in the real .dmp format, however. Maybe something for SwapMaps 2.0?

I wish I understood the .dmp format quite well enough to make it a save format, but unfortunately I don't. So far I can only really seem to edit existing maps by hand.

From what I've seen, it doesn't actually look to me as if the .dmp format is versatile enough to support the full range of possible atom containment, like a turf containing a mob that contains an obj. It appears to me that each turf is laid out with individual contents, and I know of no brace format (as in newlist() and such) for specifying contents. So this suggests that some maps simply can't be saved in .dmp format.

Lummox JR
In response to Lummox JR (#12)
Lummox JR wrote:
From what I've seen, it doesn't actually look to me as if the .dmp format is versatile enough to support the full range of possible atom containment, like a turf containing a mob that contains an obj. It appears to me that each turf is laid out with individual contents, and I know of no brace format (as in newlist() and such) for specifying contents. So this suggests that some maps simply can't be saved in .dmp format.

I think it's fair to say that the .dmp format reflects an earlier, simpler time. It wasn't designed to be nearly as complex as it is, or to have to handle a system that is as rich as BYOND now is. When the format was created, there were no overlays/underlays, for example.

Had they to do it over again, I suspect Dantom would take a significantly different approach. (I don't know, that's just my guess.)

Which implies to me that we shouldn't attempt to twist the format into a complexity it wasn't setup to handle. For libraries such as yours, it's best to move forward with more flexible approaches, like using savefiles and such.

I don't know what SwapMaps actualy does in this regard, though I expect to be using it eventually. My first ambitious RPG did a bunch of the SwapMaps stuff, but not in such a flexible manner. I will be happy to make use of someone else's work in this area!
When I made Spell Bubbles. I tried to get everything down to just two functions.... add bubble and remove bubble.

lol now modifing my code LOL good luck. I am prolly the messiest coder ever.