Skip to content

v1.0.0-alpha.1

Pre-release
Pre-release
Compare
Choose a tag to compare
@github-actions github-actions released this 16 Jul 19:31
· 482 commits to main since this release
v1.0.0-alpha.1
e87da4a

Important changes

This new alpha brings new capabilities for Dojo at different levels:

  • A new model API to interact with your models data. When a model is processed by the Dojo plugin, <ModelName>Trait and <ModelName>EntityTrait are generated. The <ModelName>Trait deals with the full model data (including the keys). The <ModelName>EntityTrait doesn't contain the key, only the data and the entity_id (currently stored with a __id field).
    They allow interacting with model's data in an efficient manner, without expanding more code at each use (which was the case using the macro):

    use path::to::MovesTrait;

// Each key of the entity is a distinct parameter after the world.
let mut moves = MovesTrait::get(world, player);
moves.remaining -= 1;
// They keys being present in the type, only the world is required to set the data.
moves.set(world);
moves.delete(world);

    If you only have to deal with entity_id instead of all the keys, you can use the <ModelName>EntityTrait:

    // The entity may come computed from the keys, or a simple `felt252` holding the value.
let move_id = MovesTrait::entity_id_from_keys(player);
let move_id = registered_moves[n];
// Get in the same fashion as before, but only using the `entity_id`. This returns a `<ModelName>Entity` and not the full model with keys.
let mut moves = MovesEntityTrait::get(world, move_id);
moves.remaining -= 1;
// `Update` is used over `set` to make the distinction here with a `set` where keys are used to ensure Torii
// knows the full keys.
moves.update(world);
// You can also delete:
moves.delete(world);

    Both of the traits are using the same Torii event (EntityUpdated), which makes them both usable right away in Torii with subscriptions.

    Even if available in the API, the get/set_member_name(...) are not yet available in Torii. They may not be used to now as it will compile, but Torii will not index such changes.

    The macros get!, set! and delete! are still available, and use the new functions under the hood (hence more efficient and producing less code).

    Examples: entity_id access and get.

  • Namespaces have been improved, to support the re-use of models from other libraries.
    The new way to configure namespace if the following:

    [tool.dojo.world.namespace]
default = "dojo_examples"

    Having this instead of the package name as default namespace, allow configuration across profiles.
    Now, if you need to import a library, you may want to map the namespace to choose your own:

    [tool.dojo.world.namespace]
default = "dojo_examples"
mappings = { "armory-Flatbow" = "dojo_examples_weapons", "bestiary" = "dojo_examples_foes" }

    In this case, you can use the mappings. You can define a mapping for a very specific model/contract using its tag (armory-Flatbow) to define its namespace into your project. Or you can choose to remap all the models/contracts using the namespace name (bestiary).

    All the other models/contracts that don't have mappings, will be using the default namespace.

    Due to compiler limitations, there are two edge cases:

    • If in your project you want to change the namespace some models/contracts using the attribute #[dojo::contract(namespace: "nm") then you will have to use #[dojo::contract(namespace: "nm", nomapping: true)] to ensure it doesn't fallback into the default namespace.
    • When you write a library that exposes models, if you want the user to be able to define mappings specific for your library or targeted models/contracts, you must define an explicit namespace using the attribute #[dojo::model(namespace: "nm")]. This way, nm will be able to be remapped by the user of your library.

    Examples: defining a library model and remapping the model's namespace specifically.

    Remember that if you want the model to be registered by sozo, you will have to declare it inside the build-external-contract as shown here. Without this, you can still using the model/contract, but it will not be registered and managed by sozo.

  • Add support for Cairo features: you can now use the features (similar to rust for those familiar with the crab language). Using features, you can determine which part of a Cairo module has to be included at compile time.

    [features]
# Default is a special feature, where you can enable some features by default without passing them explicitly.
default = ["dungeon"]
# Defining a feature is only adding a line like this.
dungeon = []

    Then in the code, you can do the following:

    #[cfg(feature: 'dungeon')]
use dungeon::Goblin;

    It is important to note that, in Cairo, you can't use the #[cfg(feature: ...)] inside a function to add/remove some statements. But can be use anywhere else (mod, use, struct, etc...).

  • A new macro selector_from_tag! to compute the selector of a model/contract based on it's tag, expanded at compile time.

    let selector = selector_from_tag!("dojo_examples-Moves");

  • World's contract registry: With the rework of the world to support the new model API, a contracts registry has also been added. This contract's registry allows you to query the world for a specific contract's address in a very deterministic manner.

    let (class_hash, address) = world.contract(selector_from_tag!("dojo_examples-Moves"));

    This avoid having to inject addresses during initialization, and not have to change the code each time contract's address may change.

  • Scarb now allows you to use a merge strategy when defining multiple profiles. This means, for each profile you declare, all the keys that are not found for a profile will fallback on the default profile (dev). Example here.

  • SDKs: With this new release, the SDKs will be updated, to ensure you have the tag as identifier for your queries and subscriptions to be compatible with the new changes.

What's Changed

  • refactor: update manifest structure by @lambda-0x in #2153
  • refactor(torii-grpc): empty hashed keys in subscription match all entities by @Larkooo in #2154
  • feat: bump cairo and scarb to latest nightly by @glihm in #2152
  • feat(dojo-bindgen): add namespace to unity bindgen by @Larkooo in #2155
  • fix selector functions for models and contracts by @remybar in #2156
  • chore: use version sensitive deps from katana-cairo + some unused deps clean up by @kariy in #2163
  • added missing_debug_implementations lint by @g4titanx in #2016
  • bump account_sdk to rev 199d87d on main by @kariy in #2165
  • fix(compiler): use provided metadata to support feature flags by @lambda-0x in #2167
  • feat(sozo): support for feature flags by @lambda-0x in #2112
  • fix: use merge-strategy instead of copying profile by @lambda-0x in #2170
  • fix(sozo): remove generate overlay command by @lambda-0x in #2168
  • fix(sozo): ensure overlays can support any resource type by @glihm in #2169
  • refactor(katana-db): database transaction abstractions by @kariy in #2171
  • refactor(katana-db): main database trait by @kariy in #2173
  • refactor(torii): remove executor from world table & write class hash by @Larkooo in #2166
  • feat: add support for model from other libraries by @glihm in #2172
  • feat(core): model get/set functions by @remybar in #2159
  • fix cairo file metadata for contracts and models by @remybar in #2175
  • feat: add support for signed integers by @EjembiEmmanuel in #2161
  • Prepare release: v1.0.0-alpha.1 by @tarrencev in #2178

New Contributors

Full Changelog: v1.0.0-alpha.0...v1.0.0-alpha.1

Contributors

tarrencev, glihm, and 6 other contributors
Assets 6
Loading