Vrixyz
commented
1 month ago
- Would it make sense if the
<load ... />substitution also added the'''rustbacktics automatically?
I decided against because the substitution is language agnostics, I'll want to use the same code for javascript injections. It also allows to add other code snippet if needs be. I'm not feeling too opinionated in this though.
- Could we rename
<load ... />into<example ... />?
I have no strong opinion on this either ; this injection could work to load another markdown file though (it's probably not a good idea as there are better tools), but I felt "load" conveys better its inner working. Alternatives considered were "file", "inject"...
Testing all examples is very time consuming, and checking them all by hand is error prone. Having an easy way to test them would help.
What this PR does:
docs-examples, containing Rust examples (I didn't start to work on javascript)cargo check --examples<load>tag (in the mindset of<bevy>,<rust>,<js>...docs-examplesalso contains a crateinject_code, which is responsible to parse a file, detect the load tag, and inject the code inside, keeping only relevant marked lines.templates_injectedis created, containing all the templates with injected code,in order to play well withPUBLISH_MODE=0, so we can review templates on their aggregated page../diff_with_branch.shinject_file/tmp_diffis created, containing diffs from template to injected files. Mostly for debug purposes, not sure if we keep it, I might turn this behaviour off by default./generate_user_guides.shscript is updated to do the injection automatically.Solution considerations
It's a bit unfortunate that it creates an indirection when editing the docs (we have to go check the content of the file linked), but the alternatives being: - 🔴 Don't change anything, and risk errors at each new releases - 🔴 Inverse the source of truth: create a rust project from the documentation. It's a bit more complicated to do, and risks having very big files for the doc
Migration fixes or modification details (long)
- colliders: - collider type modification: sensor component added/removed - colliderposition: z position moved in 2d examples ; missing rparenthesis ; missing rangle - colliders solver/group flags ( https://github.com/dimforge/rapier.rs/issues/75 ) - ActiveCollisionTypes::KINEMATIC_FIXED -> KINEMATIC_STATIC - ⚠️ : TODO: rename STATIC to fixed in bevy_rapier - ColliderFlagsComponent -> ActiveHooks - RigidBody without GlobalTransform, with child ; causing runtime warning. - I added GlobalTransform - Quat::IDENTIY -> Quat::IDENTITY - joints: - local_anchor -> local_anchor1 - added colliders + SpatialBundle, maybe too verbose but more useful. - Vector3::x_axis() -> Vec3::X (use bevy rather than na) - useless mut :shrug: - CharacterController: - That collider optionally be attached to a rigid-body - character_controller -> character_controllers - to_radians() needs explicit type - modify_character_controller_autostep -> modify_character_controller_up - modify_character_controller_slopes -> read_character_controller_collisions - Scene queries: - shapecasting max_toi now `ShapeCastOptions` - ⚠️ : would be neat to document those - ⚠️ : I'd appreciate an example to show how to retrieve the hit/normal in global space. (smth like globalTransform.TransformPoint/Direction) - ⚠️ : + wrong docs (https://docs.rs/bevy_rapier3d/latest/bevy_rapier3d/plugin/struct.RapierContext.html#method.cast_shape) ; also related discussion on discord: https://discord.com/channels/691052431525675048/1242987460288315425/1245383515953037424 - intersections_with_point takes an owned Vect ; (maybe a ref is better?) - intersections*: a few borrow parameters are actually owned - QueryFilter: IntersectionGroup -> CollisionGroup - \+ similar to ( https://github.com/dimforge/rapier.rs/issues/75 ) - QueryFilter: rather than using (the complicated) userdata, I hooked up to a bevy query. - advanced collision detection - collide handle -> `ColliderHandle` - sample code to add the marker `ActiveEvents::CONTACT_FORCE_EVENTS` ? - ⚠️ : check solo lines codes shared with rust/js, in bevy anyway: has_any_active_contact -> has_any_active_contacts - manifold data -> .raw.data + direct properties (not function calls) - contacts_with -> contact_pairs_with - intersections_with -> intersection_pairs_with - App::build -> App::new Bugs: - ⚠️ : pixels_per_meter doesn't work ? - ⚠️ : CharacterController broken (with bevy) - grounded becomes sometimes false (https://github.com/dimforge/bevy_rapier/issues/377) - update translation must be in FixedUpdate - examples lack a `SpatialBundle` or `TransformBundle` - doesn't work without a collider ? (maybe just needs a shape?) - 2 characterController on top of one another end up blocked. - solver_contacts ref needed for borrow checker + function is actually a property.
Tutorial flow notes
My feeling over going through the bevy user guide is quite positive, as it's very precise, and useful to make sense of how it works together. It might be bit more resembling to a reference than a "guide" though, with a vibe of "it will all make sense when you finish, promise". Suggestions: - avoid code snippet which are `too isolated, prefer slightly more lines of code but usefulness. - or now that we have "context" available, we could have *less* lines of code but better context - i.e.: avoid the redundant `command.spawn` for an `insert` ; not obligated to end lines with `;` - maybe use highlight code from docusaurus ? https://docusaurus.io/docs/markdown-features/code-blocks#line-highlighting Also, there's a lot of code shared withing this user guide, we might want to consider consolidating the crates documentation for reference, and link to those rather than re-implementing and maintaining our own rustdoc ? Or study if we can apply some of ideas from https://diataxis.fr/