Alpha 4 is here!

Alpha 4 targets Defold 1.4.0

Changes to OOP

Alpha 3 introduced the Object Oriented Programming API to DefoldSharp, but in an early prototype form. It has been revised in Alpha 4 to be more robust.

• Caching for built-in Defold components (sprite, tilemap, etc) has been REMOVED. While this sounded like a good idea, and allowed state tracking beyond what Defold includes, reality proved it to be fragile. It required strict adherence to the OOP methodology: trying to mix the two APIs would desynchronize what the OOP API thought the component state was. For instance, if you used the Defold API to set a sprite's sprite, the OOP Sprite would be unaware of the change and still report the old cached image name. However, the fatal blow came from component destruction. There was simply no way to be notified that a built-in component had been destroyed. This meant that existing components could become either stale and point to a component that no longer existed, or worse, point to a new instance that lived at the same url, but had none of the cached values.

  Because of this, Caching has been removed for built-in components. However, they are intentionally unsealed classes, so you are free to add your own caching layer on top.

• User components are still indexed. Because we can inject code to set up and tear down the reference, user components are still cached, and fetching a component from multiple locations will yield the same instance of the component. However, the API to access and create component references has been improved. While the Component.At<> notation is still available, directly crafting the ComponentLocator can be cumbersome, so it is now possible to fetch a sibling component by accessing the GameObject:

//from within a GameObjectScript
//Access user or built-in sibling components by providing the name (note the usual `#` prefix is missing!)
_factory = Gameobject.Component<Factory>("factory");

This works because the Gameobject reference inherently knows its id. Consequently, accessing one of your custom user components this way will actually fetch the actual component. This may change in future versions to return a reference, which can be tracked and invalidated when the component is destroyed. As of now, because the actual component is returned, existing lookups can access components after destruction. As stated, this may be changed in Alpha 5, once I have the opportunity to test impact of changes.

Changes

• Built-in components no long offer caching functionality. It is merely wrappers on the built-in components, with the same limitations.
• User components are indexed, and now clean up when destroyed.
• Custom user components now can access functions on the underlying gameobject.
• Added Sound OOP API
• Added Debug API. Also includes option to toggle debug hooks when operating in debug under the editor (F5). Turning this off then not needed can greatly improve performance (but disables breakpoints until reenabled)
• Added Math API
• Added OS API
• Added CollectionProxy OOP API
• Added missing go.animate and gui.animate
• Vectors are now double-based
• Very basics of OOP gui node access

Getting Started

Either download the below and follow the Alpha 1 instructions, or hop over to the https://github.com/RealityStop/DefoldSharpExamples for a jump start

Alpha 3 has arrived, with substantial changes.

Beginning OOP API

After adding the example project, I settled down to work on the OOP API. This API needs to handle built-in components (such as Sprite, Factory, Tilemap) as well as user components scripts (such as Player, Turret, etc). Each of these presents special challenges, and combining them into a single API has taken some time.

The core of the API is the Component API, which can be used to locate either type of component:

protected override void init()
{
    _sprite = Component.At<Sprite>(new ComponentLocator("sprite"));
}
//later...
_sprite.HorizontalFlip = true;
_sprite.PlayFlipbook(dodge);

Components can be cached for convenience, and built-in components offer the ability to cache their internals, which is safe to do if you are only accessing their members via the OOP API. If you are mixing the standard Defold API (tilemap.set_tile) with the OOP (mytilemap.SetTile) then it is not safe the cache the internals, as the data could change without the OOP representation being aware of the change.

The component API is likely to change between Alpha 3 and Alpha 4. In particular, better control over component destruction and memory management are planned. However, Alpha 3 is a large step forward, and we need to see how the proposed API works in more scenarios before we develop it further.

Changes:

• Standard messages (ex: "animation_done") added and compatible with existing Message.IsMessage system.
• fixed API calls with optional parameters containing a '-'
• Url may now be used as a key in collections
• Fixed missing sprite.play_flipbook
• Added OOP API for both built-in components (Sprite, Tilemap, Factory, CollectionFactory included in Alpha 3) and user components.

As always, it is recommended to look at the Defold Sharp Examples project for examples of how to use the latest version.

***** Known Limitations:
Component references are never cleaned up. It is entirely possible to access things after they are destroyed, or to create new ones at the same Url and cause issues. These will be cleared for Alpha 4. This alpha is for playing with, trying the API and evaluating the next steps. We're not ready for production projects yet.

Alpha 2 released

After a documentation delay, it was nice to get back to the code and start hammering out some of the details.

Alpha 2 is a fairly small changeset, but solves a major headache with Alpha1:

• Now includes optional parameter variants, so you can now call go.get_position() and not have to specify the id each time.
• Fixed Vector2 OOP api to function more transparently. In particular, math operations with Vector3s are now included.

Installation instructions remain the same as Alpha 1

During Alpha, installation is a bit... more involved. This will get easier as it gets closer to full release.

• Create a new Defold project.
• Create an src folder that will contain the C# code.
• Download the .zip and unpack to the src folder.

  src\build.cmd and src\defold should exist

• Create a bin folder
  • Download the latest Compiler and CoreSystem.lua from (DefoldCSharpCompiler)[https://github.com/RealityStop/DefoldCSharpCompiler/releases]
  • Place both in the bin directory

    Path to compiler should be bin\compiler\CSharp.lua.Launcher.exe
    Path to CoreSystem should be bin\CoreSystem.Lua\All.lua