chore: world, contracts and builder cleanup and updates#54
Conversation
… links and more links, some common infromation flow rework for building
fc-tezza
requested review from
0xxlegolas,
CCP-2FaceMonkey,
CCP-Wintermute and
ccp-raudur
as code owners
fc-tezza
changed the title
|
|
||
| For extension development and integration follow the [high-level build steps](../introduction#high-level-build-steps). | ||
|
|
||
| ### Smart Gate API overview |
There was a problem hiding this comment.
isnt Smart Gate Extension API and Smart Gate API overview the same ? also this information might a duplicate of what is in https://docs.evefrontier.com/smart-assemblies/gate#linking-gates that it needs to be owned by the same person.
and default and custom behaviour is also in https://docs.evefrontier.com/smart-assemblies/gate
and I dont think the View functions and anchor function information is useful here.
Its mostly for the game and builders wont really need it
might be a good idea to remove this section
There was a problem hiding this comment.
I though it may be useful for builders to have a context of ALL of the API endpoints in an assembly contract for interaction not just the extendable functions.
When you integrate with an assembly as a builder, your extension logic has access to all public functionality as well as the extendable API. and it is useful to generally know what public functionality is available I think.
Those other descriptions are non-technical and behavioral... I think is useful to have technical reference to the actual functions in code for builder context. Currently we don't really have a place for that.
Hence the reasoning for API vs Extension API, Extension API defines explicitly the extendable endpoints. The General API section is supposed to give technical context (not just behavioral description) to everything accessible on the assembly that could be used or is useful for extension integration.
But if it is not useful then I can remove it.
| The [world storage unit module](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/assemblies/storage_unit.move) exposes: | ||
|
|
||
| Custom contracts use the **typed witness pattern**: define a witness struct (`Auth`) and register it on the storage unit. | ||
| - **Lifecycle & ownership:** Owner-cap–guarded `online` / `offline`, metadata updates, and admin flows (anchor, unanchor, energy source). View functions: `status`, `location`, `owner_cap_id`, `energy_source_id`, `inventory`, `is_extension_frozen`, `has_open_storage`, etc. |
There was a problem hiding this comment.
Can we remove the Lifecycle & ownership alone ? introducing terms like anchor and view functions does not go with the build flow. It could go as a prerequisite
There was a problem hiding this comment.
I think a rework is worth consideration rather than outright removal as per my comment here.. we can discuss and come to an alignment
| Custom contracts use the **typed witness pattern**: define a witness struct (`Auth`) and register it on the storage unit. | ||
| - **Lifecycle & ownership:** Owner-cap–guarded `online` / `offline`, metadata updates, and admin flows (anchor, unanchor, energy source). View functions: `status`, `location`, `owner_cap_id`, `energy_source_id`, `inventory`, `is_extension_frozen`, `has_open_storage`, etc. | ||
|
|
||
| - **Inventories:** Storage units have multiple inventory slots keyed by ID: |
There was a problem hiding this comment.
This section is great and good enough
There was a problem hiding this comment.
maybe I should rework the API outline section to be more like this for all build flows.. is your suggestion that we just don't need the Lifecycle and Ownership section for context?
The issue I see is that we have a "description" section where we generally talk about behavior and game related usage.
And we have a very strict build section that focuses only on the extendable API endpoints themselves.
But we don't have a place to talk about the module functionality overall (from a technical perspective) which I think gives good context to builders who are going to build extension use-cases on top of it.
So basically, that was the goal of including the more general API and lifecycle etc sections... to give builder technical context more generally than just the explicit extension endpoints.
| ``` | ||
|
|
||
| **Extension: deposit / withdraw** (main inventory; your extension calls these with your `Auth` witness): | ||
| **Freeze extension config (optional, irreversible):** Owner can call this after authorizing an extension so the extension cannot be changed. |
There was a problem hiding this comment.
can we remove the freeze extension from the happy path here ?
its already available in the introduction section so it should be good enough.
There was a problem hiding this comment.
the introduction section only describes freezing.. I thought we should have a code reference on how to freeze.. but I didn't feel like that belonged in the introduction
| The [world turret module](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/assemblies/turret.move) exposes: | ||
|
|
||
| Custom contracts use the **typed witness pattern**: define a witness struct (`Auth`) and register it on the turret. | ||
| - **Lifecycle & ownership:** Owner-cap–guarded `online` / `offline`, metadata updates, and admin flows (anchor, unanchor, energy source). View functions: `status`, `location`, `is_online`, `owner_cap_id`, `energy_source_id`, `extension_type`, `is_extension_configured`, `is_extension_frozen`, etc. |
There was a problem hiding this comment.
same here, lifecycle section can be removed as it does not much help in the build section
There was a problem hiding this comment.
| ## Extension Integration | ||
|
|
||
| 1. **Define a witness struct** (e.g. `public struct TurretAuth has drop {}`) in your Move package. | ||
| 2. **Implement `get_target_priority_list`** with the same signature as the [world turret module](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/assemblies/turret.move): |
There was a problem hiding this comment.
instead of deleting this can we add BCS link to this . I dont see why 2 & 3 needs to be replaced with Turret API overview where it duplicates the same information https://docs.evefrontier.com/smart-assemblies/turret#behaviours
| Custom contracts use the **typed witness pattern**: define a witness struct (`Auth`) and register it on the turret. | ||
| - **Lifecycle & ownership:** Owner-cap–guarded `online` / `offline`, metadata updates, and admin flows (anchor, unanchor, energy source). View functions: `status`, `location`, `is_online`, `owner_cap_id`, `energy_source_id`, `extension_type`, `is_extension_configured`, `is_extension_frozen`, etc. | ||
|
|
||
| - **Target priority:** The game calls `get_target_priority_list` whenever target behaviour changes (e.g. ship enters range, starts or stops attacking). Without an extension, the world module uses default rules. With an extension, the game resolves the package ID from the authorised type and calls **your** package’s `get_target_priority_list` with the same signature — you return a **BCS** ([Binary Canonical Serialization](https://sdk.mystenlabs.com/sui/bcs); Sui’s standard encoding format for on-chain data) encoded `vector<ReturnTargetPriorityList>` (target_item_id, priority_weight). The game shoots the highest-priority target; ties are resolved by list order. |
There was a problem hiding this comment.
this information is mostly duplicate from : https://docs.evefrontier.com/smart-assemblies/turret#behaviours
| For extension development and integration follow the [high-level build steps](../introduction#high-level-build-steps). | ||
|
|
||
| After authorization, the game **resolves the package ID** from the authorised type and calls `get_target_priority_list` in your extension package whenever it evaluates targets for that turret. | ||
| ### Turret API overview |
There was a problem hiding this comment.
Not sure if we need this huge refactoring for turret build. the existing API section seems to have all the same information without duplicates form the https://docs.evefrontier.com/smart-assemblies/turret
There was a problem hiding this comment.
the goal here was to make the reader flow for all of the build sections (Storage, Gate, Turret) consistent and standardized
same sections and flow for all build documents
so the rework here is to add relevant general contract technical reference information on top of the more general behavioral descriptions in https://docs.evefrontier.com/smart-assemblies/turret
0xxlegolas
left a comment
0xxlegolas
left a comment
There was a problem hiding this comment.
- smart contracts and quick start sections looks good
- for smart assemblies especially, except for adding open inventory api I dont see the value of major refactoring the sections.
As per my replies here - https://github.com/evefrontier/builder-documentation/pull/54/changes/BASE..0e734af2821b459953412e73449a232b7131f4d4#r2921668049 The primary gap I see is that we have two sections for assemblies..
We have no good place for general relevant technical information about the assembly contract as a whole which is useful for extension integration (not just the extendable endpoints). So this re-work was an attempt to bring that context and information into the build docs for assemblies. Instead we could embed this information in the assembly README.md with the non-technical behavioral descriptions, but it feels more relevant to builders in the build.md So the current iteration puts this information before the direct extendable builder flow as technical context for builders much like the pre-requisites, etc... |
3 participants
TL:DR, primary updates: unified assembly build flow, capability pattern, location reveal, new extension freeze, storage unit added functionality, and fixes.
Assembly build guides
deposit_to_open_inventory,withdraw_from_open_inventory) andfreeze_extension_config. Gate/Turret: view lists includeowner_cap_id,energy_source_id,is_extension_frozen. Turret: BCS defined.Smart Character
OwnerCap<Character>cannot be transferred to an address (enforced inaccess_control.move). Warning not to transferPlayerProfile.Move patterns & ownership
EVE Frontier world explainer
reveal_location,LocationRegistry). Primitives: added deep-dive links.Misc