Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: New projects, tutorials, and extensive extension methods to enhance functionality and documentation #158

Merged
merged 32 commits into from
Sep 21, 2024

Conversation

VaclavElias
Copy link
Collaborator

@VaclavElias VaclavElias commented Sep 15, 2024

PR Classification

New feature and documentation update.

PR Summary

This pull request introduces new projects, tutorials, and extensive extension methods to enhance functionality and documentation.

  • Updated Stride.CommunityToolkit.sln to include new projects and modified existing ones.
  • Added new tutorials on easing functions and raycasting in easing.md and pick-and-aim.md.
  • Introduced new extension methods for collections, camera components, and entity components in various files.
  • Enhanced ModelComponentExtensions with methods for setting material parameters.
  • Added new namespaces and classes for mathematical operations, prefab instantiation, and script system extensions.

@VaclavElias VaclavElias added the engineering Makes the pull request to appear in the "Engineering" section of the next release note label Sep 15, 2024
@VaclavElias VaclavElias changed the title Feat 01 adding extensions More extensions Sep 15, 2024
Enhance XML docs and update method signatures

- Added detailed XML documentation comments to `EntityExtensions` class and methods.
- Updated method signatures to use nullable return types.
- Standardized exception comments for `ArgumentNullException`.
- Clarified documentation for methods retrieving multiple components.
- Adjusted formatting for the closing brace of the class.
- Added T4 template `EntityExtensions.GetComponents.tt` to generate `EntityExtensions.GetComponents.cs`.
- Included helper methods in T4 template for number-to-word conversions.
- Updated `Stride.CommunityToolkit.csproj` to include generated file as design-time, auto-generated.
- Added service reference with GUID `{508349b6-6b84-4df5-91f0-309beebad82d}` to project file.
Introduce Stride.CommunityToolkit.Collections namespace and add
CollectionExtensions class with three new extension methods:
- AddRange<T>: Adds elements from IEnumerable<T> to ICollection<T>.
- EnqueueRange<T>: Adds elements from IEnumerable<T> to Queue<T>.
- PushRange<T>: Adds elements from IEnumerable<T> to Stack<T>.
All methods throw ArgumentNullException if inputs are null.
Updated summary, param, returns, and exception tags for clarity.
Added null check using ArgumentNullException.ThrowIfNull(entity).
Added a new namespace `Stride.CommunityToolkit.Engine` and introduced the `EntitySearchExtensions` static class. This class provides various methods for searching and retrieving `EntityComponent` instances within an `Entity` hierarchy using both breadth-first and depth-first search techniques. Methods include searches in children, descendants, and ancestors, with options to include or exclude disabled components. Detailed XML documentation has been added for each method.
`EntityComponentCollectionExtensions` class with methods to manage
collections of `ActivableEntityComponent` objects:
- `Enable<T>`: Enables all components in the collection.
- `Disable<T>`: Disables all components in the collection.
- `Toggle<T>`: Toggles the enabled state of all components.

Each method includes a type constraint for `ActivableEntityComponent`
and throws `ArgumentNullException` if the collection is null.
Renamed WorldToClipSpace to WorldToClip in CameraComponentExtensions.
Updated XML docs for WorldToClip to clarify transformation and return type.
Added ArgumentNullException for null cameraComponent in WorldToClip.
Introduced new WorldToClip overload with out parameter.
Updated WorldToScreenPoint to use renamed WorldToClip.
Added new WorldToScreenPoint overload with out parameter.
Included XML docs for new WorldToScreenPoint overload.
Updated CameraComponentExtensions to improve functionality and memory efficiency. Added new overloads for ScreenToWorldPoint and WorldToScreenPoint methods, including versions that take parameters by reference and by value. Modified existing methods to use out parameters for better memory management. Introduced a private ScreenToClipSpace method. Added comprehensive XML documentation for all changes.
Added a new namespace `Stride.CommunityToolkit.Collections` and
introduced a static class `DictionaryExtensions` with several
extension methods for `IDictionary<TKey, TValue>`:
- `MergeInto<TKey, TValue>`: Merges items from one dictionary to
  another, throwing `ArgumentNullException` if either dictionary
  is null.
- `GetOrDefault<TKey, TValue>`: Retrieves a value or returns a
  default if the key is not found, throwing `ArgumentNullException`
  if the dictionary is null.
- `GetOrAdd<TKey, TValue>`: Retrieves or adds a value using a
  delegate, throwing `ArgumentNullException` if the dictionary or
  delegate is null.
- Overloaded `GetOrAdd<TKey, TValue>`: Similar to the previous
  method but includes an additional condition delegate, throwing
  `ArgumentNullException` if any parameter is null.
- `Increment<TKey>`: Increments the integer value for a key, adding
  the key with a value of 1 if it does not exist, throwing
  `ArgumentNullException` if the dictionary is null.
Adds a static class `EnumerableExtensions` with three extension methods:
1. `IsNullOrEmpty<T>`: Checks if an `IEnumerable<T>` is `null` or empty.
2. `Concat<T>`: Concatenates two sequences, with the second sequence
   provided as a parameter array.
3. `ForEach<T>`: Performs a specified action on each element of an
   `IEnumerable<T>`.
Adds ListStackExtensions class with methods: Peek, Push, Pop, and
PopFront for IList<T>. Handle null and empty list cases.
Introduces `RandomListExtensions` with methods for random selection
and shuffling of collections:
- `Choose<T>(this Random random, IList<T> collection)`: Selects a
  random item from a collection, throws exceptions for null or
  empty collections.
- `Choose<T>(this Random random, params T[] collection)`: Selects a
  random item from an array, throws exceptions for null or empty
  arrays.
- `Shuffle<T>(this Random random, IList<T> collection)`: Shuffles
  the elements of a collection in place, throws exceptions for null
  collections.
@VaclavElias VaclavElias changed the title More extensions fea: New projects, tutorials, and extensive extension methods to enhance functionality and documentation Sep 21, 2024
@VaclavElias VaclavElias changed the title fea: New projects, tutorials, and extensive extension methods to enhance functionality and documentation feat: New projects, tutorials, and extensive extension methods to enhance functionality and documentation Sep 21, 2024
@VaclavElias VaclavElias merged commit cfc78aa into stride3d:main Sep 21, 2024
@VaclavElias VaclavElias deleted the feat-01-adding-extensions branch November 26, 2024 22:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
engineering Makes the pull request to appear in the "Engineering" section of the next release note
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant