OmniBuilder: المرجع التقني المطلق OmniBuilder: Absolute Technical Reference
تم تصميم هذا المرجع لتوثيق كل ميزة، علامة تبويب، مُعلمة، ونموذج تفاعل في حزمة OmniBuilder بدقة مطلقة. هذا هو الدليل النهائي الذي يتطابق مباشرة مع البنية الداخلية للإضافة. This reference is designed to document every single feature, tab, parameter, and interaction model in the OmniBuilder suite with absolute precision. This is the definitive manual, mapping directly to the plugin's internal architecture.
1. مساحة العمل العالمية والواجهة 1. Global Workspace & Interface
تنقسم واجهة المستخدم إلى وضعين رئيسيين: واضع الأصول (Asset Placer) و وضع الملصقات (Decal Mode). يوفر الشريط العلوي تحكمات عالمية تشمل: The UI is divided into two main operation modes: **Asset Placer** and **Decal Mode**. The top bar provides global controls, including:
- تصفية أنواع الملفات: يقيد العرض بامتدادات محددة
(
glb,gltf,fbx,objلواضع الأصول؛png,jpg,exrللملصقات).File Type Filters: Restricts the view to specific extensions (`glb`, `gltf`, `fbx`, `obj` for Placer; `png`, `jpg`, `exr`, etc. for Decals). - التصفية السريعة: عرض فوري للمجلدات "المستخدمة مؤخراً"، "المفضلة"، أو "المجموعات" المخصصة.Quick Filters: Instantly view `Recently Used`, `Favorites`, or custom `Collections`.
- شريط البحث: تصفية نصية في الوقت الفعلي عبر جميع الأصول المرئية.Search Bar: Real-time text filtering across all visible assets.
- مبدل اللغة: التبديل بين الواجهة العربية (AR) والإنجليزية (EN) ديناميكياً.Language Switcher: Toggle between Arabic (AR) and English (EN) interfaces dynamically.
- أوزان الأصول (ميزة مخفية): في ملف
user://asset_browser_v2.cfg، يمكن تعيين أوزان رقمية للأصول للتحكم في احتمالية ظهورها العشوائي عند رسم أصول متعددة محددة.Asset Weights (Hidden Feature): In `user://asset_browser_v2.cfg`, assets can be assigned numerical weights to control their random probability when painting multiple selected assets.
2. واضع الأصول: الأدوات الأساسية والمعلمات 2. Asset Placer: Core Tools & Parameters
يوفر وضع واضع الأصول ثلاث أدوات رئيسية: The Placer mode provides three primary tools:
- الفرشاة (B): ترسم الأصول في المشهد بناءً على إرسال الأشعة الفيزيائية.Brush (B): Paints assets into the scene based on physics raycasting.
- الممحاة (E): تزيل الأصول المرسومة داخل نصف قطر محدد.Eraser (E): Removes painted assets within a radius.
- التحديد (C): فرشاة تحدد الأصول المرسومة، مما يتيح التلاعب بها عن بُعد عبر اختصارات تمرير الماوس.Selection (C): A brush that selects painted assets, enabling remote manipulation via mouse scroll shortcuts.
علامة التبويب 1: الرئيسية (الرسم الأساسي) Tab 1: Main (Core Painting)
- شكل الفرشاة (Brush Shape): اختر بين الدائرة (Circle)، المربع (Square)، أو الخط (Line).Brush Shape: Choose between `Circle`, `Square`, or `Line` projection shapes.
- محاذاة السطح (Align Surface): تدوير الأصل ليتطابق مع
انحناء السطح.Align Surface: Rotates the
asset
to match the normal of the surface being painted on.
- قوة المحاذاة (Align Blend): يتحكم بقوة المحاذاة (0.0 = عمودي تماماً، 1.0 = مسطح تماماً مع المنحدر).Align Blend: Controls the strength of alignment (0.0 = completely vertical, 1.0 = perfectly flat against the slope).
- تدوير/ميل عشوائي (Random Rot / Tilt): يطبق دوراناً
عشوائياً للانعراج (0-360 درجة).Random Rot /
Tilt: Applies a random Yaw rotation (0-360°).
- أقصى ميل (Max Tilt): إذا تم تفعيله، يضيف انحرافاً طفيفاً للميل حتى الدرجات المحددة (مثالي للنباتات الطبيعية).Max Tilt: If enabled, adds a slight pitch/roll deviation up to the specified degrees (ideal for natural foliage).
- تجنب التصادم (Avoid Collision): يضمن عدم تداخل صندوق الإحاطة للأصل الجديد مع هندسة المشهد الحالية.Avoid Collision: Ensures the bounding box of the new asset does not intersect existing scene geometry.
- التحجيم (Scale Min/Max): تغيير عشوائي لحجم كل أصل ضمن هذا النطاق.Scale Min/Max: Randomizes the scale of each spawned asset within this range.
- نصف القطر (Radius): الحجم المادي للفرشاة. عيّنه إلى 0 لوضع دقيق بنقرة واحدة.Radius: The physical size of the brush. Set to 0 for single-click precision placement.
- قوة الممحاة (Erase Strength): الاحتمالية (1-100%) لحذف الأصل داخل نصف قطر الممحاة في كل إطار.Erase Strength: The probability (1-100%) that an asset within the eraser radius will be deleted per frame.
- الكثافة (Density): عدد الأصول المتولدة في كل نقرة
فرشاة.Density: The number of assets spawned
per
brush dab.
- تضاؤل الكثافة (Density Falloff): يقلل احتمالية التوليد بالقرب من حواف الفرشاة لتلاشي أنعم.Density Falloff: Reduces spawn probability near the edges of the brush radius for a softer fade.
- التباعد (Spacing): يفرض مسافة دنيا صارمة بين الأصول لمنع التداخل.Spacing: Enforces a strict minimum distance between painted assets to prevent overlap.
- نطاق الأمان (Safe Rad): نطاق الفحص عند تفعيل تجنب التصادم.Safe Rad (Avoidance Radius): The clearance sphere checked when `Avoid Collision` is enabled.
علامة التبويب 2: متقدم Tab 2: Advanced
- تصفية الميل والإزاحة (Slope & Offset
Filter):Slope & Offset
Filter:
- أقصى زاوية (Max Angle): سترفض الفرشاة الرسم على أسطح أكثر انحداراً من هذه الزاوية.Max Angle: The brush will refuse to paint on surfaces steeper than this angle.
- إزاحة Y (Y Offset Min/Max): تغرق أو ترفع الأصل بالنسبة لنقطة الاصطدام بالسطح.Y Offset Min/Max: Sinks or raises the asset relative to the surface hit point.
- قناع التصادم (Collision Mask): طبقة الفيزياء التي سيتفاعل معها شعاع الفرشاة.Collision Mask: The physics layer the brush raycast will interact with.
- تجميع تلقائي (Auto Group): يربط تلقائياً الأصول المرسومة تحت عقدة Node3D نظيفة.Auto Group: Automatically parents painted assets under a clean `Node3D` group.
- الممحاة الذكية (Smart Eraser): ستحذف الممحاة *فقط* مثيلات الأصل المحدد حالياً في المتصفح.Smart Eraser: The eraser will *only* delete instances of the specific asset currently selected in the browser.
- تصفية التحديد (Selection Filters):Selection Filters:
- تصفية الأصل المحدد: فرشاة التحديد ستلتقط فقط المثيلات المطابقة لتحديد المتصفح.Filter Selected Asset: The Selection brush will only grab instances matching the browser selection.
- تصفية الطبقة: فرشاة التحديد ستلتقط فقط المثيلات في طبقة الرسم النشطة.Filter Layer: The Selection brush will only grab instances in the active Paint Layer.
- قفل التحديد (Lock Selection): يمنع فرشاة التحديد من إفلات الهدف الحالي عند تحريك الماوس.Lock Selection: Prevents the Selection brush from dropping the current target when moving the mouse away.
- بناء المسار (Path Build - Scatter): يولد أصولاً على طول منحنى Path3D محدد.Path Build (Scatter): Generates assets along a selected `Path3D` curve.
علامة التبويب 3: النباتات (Foliage) Tab 3: Foliage
- رسم النباتات (Live MultiMesh): يستخدم MultiMeshInstance3D المدمج في جودو بدلاً من العقد القياسية لتعزيز الأداء بشكل هائل.Draw Foliage (Live MultiMesh): Uses Godot's `MultiMeshInstance3D` directly instead of spawning standard Nodes for massive performance gains.
- ميزانية النباتات (Foliage Budget): مدير كثافة محلي لمنع انخفاض معدل الإطارات.Foliage Budget: A localized density manager to prevent framerate drops.
- توزيع الضوضاء (Noise Clustering): يوزع الأصول باستخدام خريطة ضوضاء Simplex بدلاً من العشوائية الموحدة.Noise Clustering: Distributes assets using a Simplex noise map instead of uniform randomness.
علامة التبويب 4: المحاذاة (الآليات المعمارية) Tab 4: Snap (Architectural Mechanics)
تُفعل حصرياً عندما يكون نصف قطر الفرشاة 0. Activates exclusively when the Brush Radius is 0.
- التقاط الشبكة (Grid Snap): يجبر الإحداثيات على التدوير لخطوات الشبكة المحددة.Grid Snap: Forces absolute coordinates rounding to the `Grid Snap Step`.
- الإسقاط على السطح (Drop Surface): ينقل الأصل الموضوع/المحدد للأسفل مباشرة حتى يصطدم بمصادم فيزيائي.Drop Surface: Teleports the placed/selected asset straight down until it hits a physics collider.
- تعبئة الصندوق (Box/Area Fill): انقر واسحب لتحديد حجم مستطيل، وسوف تملأ الإضافة الحجم مع احترام إعدادات التباعد.Box/Area Fill: Click and drag to define a rectangular volume. The plugin mathematically fills the volume respecting the `Spacing` setting.
- الرسم المستمر (Continuous Draw): اضغط باستمرار على Shift أثناء السحب لقفل الحركة على محور واحد لرسم خط مستقيم من الأصول.Continuous Draw: Hold `Shift` while dragging to lock movement to a single axis, drawing a perfect straight line of assets.
- خيارات الالتقاط المعماري (Arch Snap Options): التقاط للمقابس (Sockets)، الحدود (Bounds)، أو الرؤوس (Vertex).Arch Snap Options: Snaps to Sockets, Bounds, or absolute nearest geometry Vertex.
علامة التبويب 5: طبقات الرسم (Paint Layers) Tab 5: Paint Layers
- تعمل مثل طبقات فوتوشوب لمشهدك ثلاثي الأبعاد. تتضمن إجراءات مثل الإضافة وإعادة التسمية والحذف، وأيقونات الرؤية (العين)، والقفل، والعزل (Solo).Functions like Photoshop layers for your 3D scene. Includes actions to Add, Rename, Delete, Visibility toggle, Lock toggle, and Solo focus mode.
علامة التبويب 6: مساعد التصادم (Collision Helper) Tab 6: Collision Helper
- معالج دفعة للأصول التي تفتقر للفيزياء. يمكنه توليد أو تحديث عقد StaticBody3D و CollisionShape3D مُحسنة للأصول المحددة.A batch-processor for assets lacking physics. Generates or updates optimized `StaticBody3D` and `CollisionShape3D` nodes for the selected assets.
علامة التبويب 7: مستوى التفاصيل (LOD) Tab 7: LOD (Level of Detail)
- نظام رؤية مُخزن مؤقتاً وعالي الأداء. يتحكم في تلاشي المجسمات بناءً على المسافة لتقليل استهلاك المعالج.A highly optimized, cached visibility system. Controls mesh fading based on distance to save CPU.
علامة التبويب 8: الإعدادات المسبقة (Presets) Tab 8: Presets
- حفظ التكوين الدقيق لكل منزلق ومفتاح تبديل في إعداد مسبق مخصص.Save the exact configuration of every slider, toggle, and setting into a custom preset.
علامة التبويب 9: الإعدادات (Settings) Tab 9: Settings
- إعادة ربط المفاتيح الفيزيائية لجميع الأدوات مع التحقق التلقائي من التعارضات.Rebind physical keys for all tools. Checks for conflicts automatically.
3. وضع الملصقات: محرك PBR 3. Decal Mode: PBR Engine
يزيل وضع الملصقات الإعدادات ثلاثية الأبعاد ويوفر مجموعة أدوات إسقاط ثنائية الأبعاد مضبوطة بعناية. The Decal Mode strips away 3D settings and provides a highly tuned 2D projection toolset.
- تبديل المادة (Swap Texture): زر بنقرة واحدة لاستبدال نسيج الملصق المرسوم بالتحديد الحالي للمتصفح.Swap Texture: A one-click button to replace the texture of a painted Decal with the current browser selection.
- المعلمات: الحجم (Size)، العمق (Depth)، الشفافية (Opacity)، التباعد (Spacing)، طبقة الاستبعاد (Cull Layer).Parameters: Size, Depth, Opacity, Spacing, Cull Layer.
- محرك PBR التلقائي (Auto PBR Engine): عند التفعيل، تقوم الإضافة بتحليل مسار الصورة وتجميع إسقاط مادة متكامل (يتضمن خرائط Normal و ORM) في لحظة واحدة.Auto PBR Engine: When enabled, the plugin parses the selected texture's path and builds a complete material projection instantly.
4. نظام المؤثرات المادية المتقدمة (FX System) 4. FX Material System
يتيح لك نظام المؤثرات (FX) تطبيق تأثيرات مواد متقدمة على أصول متعددة في وقت واحد دون الحاجة لتعديل كل مادة يدوياً. يستخدم هذا النظام نهجاً إجرائياً لحقن المنطق البرمجي مباشرة داخل المواد الخاصة بك. The FX system allows you to apply advanced material effects to multiple assets simultaneously without manually editing each material. It uses a procedural approach to inject logic into your materials.
🛠 كيفية الوصول والاستخدام (How to Access) 🛠 How to Access & Use
- افتح لوحة Asset Grid. Open the Asset Grid dock.
- انتقل إلى علامة التبويب FX. Navigate to the FX tab.
-
اختر وضع الاستهداف (Target Mode):
Choose your Target Mode:
- التحديد (Selection): يطبق التأثيرات فقط على العقد المحددة حالياً في منفذ العرض (Viewport). Selection: Applies effects only to currently selected nodes in the viewport.
- طبقة الرسم الحالية (Current Paint Layer): يطبق التأثيرات على جميع الأصول داخل طبقة الرسم النشطة. Current Paint Layer: Applies effects to all assets within the active paint layer.
- مجموعة الأصول (Asset Group): يطبق التأثيرات على جميع مثيلات نوع أصل معين. Asset Group: Applies to all instances of a specific asset type.
🌪 نظام الرياح لمجسمات النباتات (Wind System) 🌪 Wind System (Foliage FX)
يضيف حركة نقاط (Vertex Animation) إجرائية لمحاكاة حيوية للرياح. Adds procedural vertex animation to simulate natural wind.
- القوة (Strength): تتحكم في شدة التمايل والحركة. Strength: Controls the intensity of the sway.
- السرعة (Speed): تتحكم في سرعة تموج الرياح عبر المجسم. Speed: Controls how fast the wind ripples through the mesh.
- النوع (Type): اختر بين ثابت (Static)، تمايل بسيط (Simple Sway) (للعشب)، أو رياح الأشجار (Tree Wind) (لأوراق الشجر). Type: Choose between Static, Simple Sway (for grass), or Tree Wind (for leaves).
❄️ التأثيرات البيئية (Environment FX) ❄️ Environment FX
الجليد والثلج (Snow) Snow FX
- الكثافة (Density): يضبط كمية الثلج المتراكم على الأسطح المتجهة للأعلى. Density: Adjusts the amount of snow accumulating on upward-facing surfaces.
- اللون (Color): تخصيص لون وتظليل الثلج (الافتراضي هو الأبيض). Color: Customize the snow tint (default is white).
- النسيج (Texture): تقديم نسيج ضوضاء (Noise Map) أو رقاقات مخصص لمزيد من التفاصيل والعمق. Texture: Provide a custom noise or flake texture for more detail.
البلل والمطر (Wetness & Rain) Wetness & Rain FX
- القوة (Strength): تجعل المواد تبدو لامعة ورطبة وتزيد من دكانة اللون الأساسي (Albedo) لمحاكاة المطر. Strength: Makes materials look glossy and darkens the albedo to simulate rain.
- تجاوز الخشونة (Roughness Override): تعيين نعومة وصقل الأجزاء الرطبة بشكل يدوي ومخصص. Roughness Override: Manually set the smoothness of the "wet" parts.
- خريطة الضوضاء (Noise Map): تضيف برك مياه أو أنماط بلل عشوائية وغير متساوية. Noise Map: Adds puddles or uneven wetness patterns.
💡 المؤثرات البصرية (Visual Effects) 💡 Visual Effects
تنوع الألوان (Color Variation) Color Variation
يكسر التكرار البصري عند توزيع الأصول على نطاق واسع بتأثير صبغة لونية خفيفة وعشوائية لكل مثيل بناءً على موضعه في العالم ثلاثي الأبعاد. Breaks repetition in large-scale scattering. It adds a random subtle tint to each instance based on its world position.
- القوة (Strength): تؤدي القيم العالية إلى فروق ألوان أكثر وضوحاً وتميزاً بين الأصول المتكررة. Strength: High values result in more distinct color differences.
النبض المضيء (Emissive Pulse) Emissive Pulse
- الشدة (Intensity): أقصى درجات سطوع النبض المضيء للأجزاء المتوهجة. Intensity: The peak brightness of the pulse.
- السرعة (Speed): سرعة تنفس أو نبض الضوء وتوهجه. Speed: How fast the light breathes.
- اللون (Color): لون التوهج المضيء المطلوب. Color: The glow color.
🧪 دمج المظللات المخصصة (Custom Shader Integration) 🧪 Custom Shader Integration
يمكنك استخدام ملفات المظلل الخاصة بك .gdshader مع نظام المؤثرات (FX) بكل سهولة:
You can easily use your own .gdshader files with the FX system:
- اسحب ملف المظلل الخاص بك وضعه في خانة Custom Shader. Drag your shader file into the Custom Shader slot.
- انقر فوق رمز الترس (⚙) لفتح مفتش المظللات (Shader Inspector). Click the Gear (⚙) icon to open the Shader Inspector.
-
ستظهر جميع متغيرات الـ
uniformالمعرفة في مظللك كأشرطة منزلقة ومحددات ألوان تفاعلية تلقائياً. Alluniformparameters in your shader will appear as interactive sliders/pickers. - انقر فوق Update FX لتعميم ونشر المظلل على جميع الأصول المستهدفة. Click Update FX to propagate the shader to all target assets.
ملاحظة للأداء والسرعة Performance Note
يقوم نظام المؤثرات (FX) بتعديل مثيلات مواد فريدة (Unique Material Instances). للمشاهد الضخمة التي تحتوي على آلاف الكائنات، يرجى التفكير في استخدام أداة "دمج المواد المتعددة (MultiMesh Bake)" بعد تطبيق المؤثرات للحفاظ على معدل إطارات (FPS) مرتفع وسلس. The FX system modifies unique material instances. For massive scenes with thousands of objects, consider using the "MultiMesh Bake" tool after applying FX to maintain high FPS.
5. مصفوفة الاختصارات الشاملة 5. Master Shortcut Matrix
| الأمرCommand | الاختصارShortcut | الوصفContext |
|---|---|---|
| وضع الفرشاةBrush Mode | B | تفعيل وضع وضع العناصرActivates placement mode. |
| وضع الممحاةEraser Mode | E | تفعيل وضع الحذفActivates deletion mode. |
| وضع التحديدSelection Mode | C | تفعيل وضع التحديد والتحريكActivates grab/manipulation mode. |
| قفل التحديدLock Selection | L | تجميد العنصر المستهدف في وضع التحديدFreezes target in Selection mode. |
| تحجيم التحديدScale Selection | Shift + Scroll | تعديل الحجم الموحدAdjusts uniform scale. |
| تدوير الانعراجRotate Yaw | Alt + Scroll | التدوير حول المحور YRotates around Y-axis (5° increments). |
| تدوير التمييلRotate Pitch | Alt + Ctrl + Scroll | التدوير حول المحور XRotates around X-axis. |
| إزاحة الارتفاعHeight Offset | Alt + Shift + Scroll | رفع/خفض الأصل بشكل ديناميكيRaises/Lowers the asset dynamically. |
| نصف قطر الفرشاةBrush Radius | Ctrl + Scroll | زيادة/تقليل مساحة الفرشاةIncreases/Decreases brush area. |
| قفل المحورAxis Lock | Shift + X / Y / Z | تقييد الالتقاط بمحور معينLocks snapping to a specific axis. |
| الرسم بخطLine Draw | Shift + Drag | تفعيل منطق الرسم المستمرEngages Continuous Draw logic. |
| قلب الملصقFlip Decal | Alt + F | يعكس إسقاط الملصقMirrors the decal projection. |
| تكرارDuplicate | Ctrl + D | تكرار التحديد النشطDuplicates active selection. |