Notes translating Habitat Object Types

Porting a Habitat Type to NeoHabitat

To port an object class, this guide assumes you have a fully functional test environment up and stable and that you have selected a Habitat Object Type from the list to work on.

Modify Server Code

1. Look at the class source in the .pl1 source - it will be the primary source to port the class. file: habitat/sources/stratus/Classes/class_[habitatTypeName].pl1

   Example: habitat/sources/stratus/Classes/class_table.pl1

2. create a java class in org.made.habitat.mods using the Java standard class name conventions (capitalizing the first character)

   1. Find the org.made.habitat superclass that best applies for the inherited functionality for this habitat type.

      Example: public class Table extends Openable {

3. Copy the publics in the first block from an existing Mod, and customize them with the appropriate values from the .pl1 file.

   Example:

	public int      HabitatClass 	 () { return CLASS_TABLE; } // See Constants.java
	public String   HabitatModName	 () { return "Table"; }
	public int      capacity         () { return 5; }
	public int      pc_state_bytes 	 () { return 3; }
	public boolean  known            () { return true; }
	public boolean  opaque_container () { return false; }
	public boolean  filler           () { return false; }

4. Implement the Constructor (using @JSONMethod), encode, and decode methods. Don't forget to declare and copy out any instance variables.

	@JSONMethod({ "style", "x", "y", "orientation", "gr_state", "open_flags", "key_lo", "key_hi" })  
	public Box(OptInteger style, OptInteger x, OptInteger y, 
			OptInteger orientation, OptInteger gr_state,
			OptInteger open_flags, OptInteger key_lo, OptInteger key_hi) {
		super(style, x, y,  orientation, gr_state, open_flags, key_lo, key_hi);
	}
    
	@Override
	public JSONLiteral encode(EncodeControl control) {
	    JSONLiteral result = super.encodeOpenable(new JSONLiteral(HabitatModName(), control));
	    result.finish();
	    return result;
	}

5. Implement any custom verbs, based on behaviors defined in the .pl1 file.

   Example:

	@JSONMethod({"someInt", "someString"})
	public void VERBNAME (User from, OptInteger someInt, OptString someString) {
	    /** behavior code here, referencing someInt.value() and someString.value() */
	}

6. Make sure it compiles.

---

Modify Database

7. Add the class to the classes-habitat.json "classes" table:

   Example:

		{ "type": "class", "tag": "Table", "name": "org.made.habitat.mods.Table"},

8. Create an item to put in a context-region someplace, setting the appropriate state variables.

   Example [a table placed in "context-test", stored in the file "item-table.json"]:

	{
		"type": "item",
		"ref": "item-table",
		"deletable": true,
		"name": "My First Table",
		"in": "context-test",
		"mods": [
			{
				"type": "Table",
				"style": 0,
				"x": 145,
				"y": 140,
				"orientation": 0,
				"gr_state": 0,
				"open_flags": 1,
				"key_lo": 5,
				"key_hi": 5
			}
		]
	}

9. Stop any running server. Execute 'refresh.sh' which will load all the .json files in the current directory into the MongoDB.

10. Start the server to confirm that the classes-habitat loads. Use Telko.js or Telnet to login to the server to the test-region and make sure that the server is loading the new item correctly. NOTE: There is still more work to do, and most likely the C64 client won't yet load the object...

---

Modify Bridge

11. Working in Habitat2Elko.js - add an encoding function for the new class to encodeState(), translating any json state variables to bytes.

    Example

	var encodeState = {
		...
		Table: function (state, container, buf) { return (this.openable(state, container, buf)); },
		...
	}

12. Working in hcode.js - add an object to handle the legal client messages for this type. See the Class_Table[] assignments in the .pl1 file.

    Example:

	this.Table	= { 		
		clientMessages: {
			0:{ op:"HELP" },
			4:{ op:"CLOSECONTAINER" },
			5:{ op:"OPENCONTAINER" }
		}
	};

13. Working in hcode.js - add synchronous message encoders/decoders for any messages that this mod/type uses that aren't already coded...

    Example:

	this.translate = {
			...
			VERBNAME:     {
				toServer: function(a, m) {			// This is a format of the request on the server.
					m.someInt = a[0];			// Should match the @JSONMethod paramters
					m.someString = String.fromCharCode.apply(null, a.slice(1)); 
				},
				toClient: function(o, b) {			// This is the format of any server reply
					b.add(o.err);				// For example, the client is expecting an error code
				}		
			},
			...
	}

14. Working in hcode.js - define any missing asynchronous message handlers using a similar method, but only toClient.

    Example:

	this.SERVER_OPS = {
		...
		"WALK$": {
			reqno: 8, 			// NOTE: We can't add new messages to the c64 client.
			toClient: function (o,b) {
				b.add(o.x);
				b.add(o.y);
				b.add(o.how);
			} 
		},
		...
	}

15. You should be finished. Test by bringing up server and bridge. First connect with a Telko.js connection to see if there are any errors.

16. Reset and connect with the C64 client and try out your new object/verbs. Test with Telko.js clients as observers. Test with Telko.js clients generating the new events.

---

TBD

17. Regression testing procedure

18. Commit, test, pull request.

Done!