DESIGN: AngelScript API to support a basic chatroom with rooms and basic descriptions

[zelerin]

The AngelScript API (what is used by the scripts) needs to be significantly overhauled since it is currently just a prototype. The idea suggested to me was to make the system usable as a basic chat room, except with rooms, descriptions, etc, and being able to manipulate those at a basic level along with basic administration like creating new players. This is of course not the final goal, but a good starting point for a first release.

This issue is to discuss the design needed to do this, using the wiki as needed. Once it is designed, the issue can be closed and new issue(s) written to do the implementation.

The API needs to have stuff like this:

• dbtypes initial representation
  • players
  • exits
  • rooms
  • things
  • commands?
  • programs?
  • Groups/Capabilities?
• Security representation (so it can be viewed nicely and edited)
• Add/remove from groups and capabilities (to give people extra permissions, primarily)
• New system functions required (create player, better 'who is online' functionality, etc)?
• Simple non-interactive tool to edit documents
• Find Entities by name and type
• Fix Document so it can have long lengths for programs, but not for normal use (or allow constructor to specify size).
• Something else I'm missing?

[zelerin]

As this is the core issue needed to get v1.0 off the ground, let's get started on discussing this. There's a lot to cover here, and if it requires extra issues to cover specific pieces, then we should do so.

I think adding the functionality piece by piece will be relatively straightforward. What I want to establish up front is the structure. In particular:

• Should the API for Entities resemble their versions in dbtypes, including the hierarchy? Should it be slightly flattened, as in my prototype code, to spare the castings that will almost always be done and hide some of the complexity?
  • I'm leaning towards a semi-flattened approach, so that the average use case does not involve much (if any) casting at all. The base class would be a ContainerPropertyEntity essentially.
• Should the free functions be done as I did in the prototype, with functions hanging out in space and organized by namespace? Is there a better way to do them?
• Is there anything completely missing from the prototype's AngelScript API that should be implemented? Any aspects of the design that could be troublesome if propagated?

The result of this will be a high level class hierarchy as seen from the scripts, and major categories of functions. After that point, the existing code can be reworked to fit and functions can be added as needed.

Also, while I think the capabilities are mostly complete, any changes to those (and their associated operations) can be done as API is added. I definitely don't want an excessive number of capabilities, otherwise it gets too hard to figure out what permissions something needs.

[zelerin]

Also, there's the topic of throwing exceptions vs returning a status boolean upon error, for anything not security or resource related. I'm inclined to stay with the boolean, although the new version of AngelScript that I integrated has very basic in-language exception support.

[zelerin]

Attached is a sample starting point for the API. Let's see if this is something workable? Unfortunately I can't upload it as markdown, though it's in the right syntax.

as_api_design.txt

[hyena]

Reading through this, it looks on the level but it has some FuzzBallisms that we should probably consider before we get too far along as well as other questions:

• Programs and actions are Entities. Should they be? Is there another way to do, e.g., locking and success messages?
• Should actions and exits be the same thing?
• There's no notion of a 'Room' here except implied by Entity. Rooms are just entities with things inside them, then?
• Puppets and Vehicles are very much FBisms. Should they be done differently while we can?

Rooms could be made special but it would mean revisiting the Environment room model of FB.

[zelerin]

Good questions, all. Here's my answers:

• Entities are the root of everything accessible within the game. Not all Entity types are visible inside a room; only ContainerPropertyEntities and ActionEntities are visible because they can contain or be contained. I felt having a root type (Entity) made things a lot easier from an OO standpoint and it's something people can easily identify with, I hope. What I do want to avoid is having Programs laying about rooms and inventories in a clutter (the current design satisfies this).
• An 'ActionEntity' is the abstract root type of Commands and Exits. The major difference between a Command and Exit is that an Exit has an arrival message whereas a Command does not. Otherwise, they use whatever attributes are in the ActionEntity. There may be additional attributes specific to one or the other, but not both, in the future. Internally, it allows the code to easily branch to running softcode (or the web client knowing what might happen when something is clicked - it could have mini decorations for exits in the room) based on the type without investigating what it is linked to; primitives can force the user to link to a program or a ContainerPropertyEntity based on the concrete type of ActionEntity. I hope this makes it more clear as to my design decision. Do you still think it should be collapsed?
• The dbtypes specify how data is stored, but not the behavior. A room is simply defined by the primitives and related code as an Entity of concrete type Room. You are correct in that a Room is simply a specific type of a ContainerPropertyEntity (which allows an Entity to contain other Entities, be contained, and have application properties); it currently has no additional attributes associated with it and is basically a marker for code. I didn't like the idea of a player inheriting off of Room, for instance.
• Puppets and Vehicles may absolutely be done differently. No code has been written for them. Now's the time! If you have ideas, I am wide open to hearing them.
• Environment rooms are accomplished with Regions. Like Room, they have no additional attributes but serve as a marker for primitives. The idea is that there is a hierarchy of Regions. Regions may contain one or more Rooms. Rooms may not contain other Rooms. With security improvements, you could assign someone as being in charge of a Region and they can admin most things underneath it.

[zelerin]

I just realized I wasn't sure if you were commenting about the C++ hierarchy or the AngelScript (AS) API I listed above. It could have been either. The AS flattening provided above means that, for Programs for instance, not all methods in Entity will apply to them. The developer would have to know they can't teleport a program around, for instance. The tradeoff is that they do less casting. I also don't have puppets/vehicles specifically listed in the flattened hierarchy; they would fall under Thing.

This does admittedly make the AS API resemble FuzzBall a bit more, which may or may not be a good thing. It's at least easier to understand (less types), but perhaps it's too simple.

Also, locks, etc are again wide open to being redesigned. I have a 'lock' class in dbtypes, but it can be rewritten as needed. What ideas do you have?