حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لبرنامج Unity الأساسية

تحتوي الأقسام التالية على أوصاف للمفاهيم الأساسية لفهم واستخدام حزمة SDK للخرائط من أجل Unity.

فئة ومكوِّن MapsService

تعمل فئة MapsService كنقطة دخول للتفاعل مع حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لبرنامج Unity. وهي تتضمن ApiKey، وتعرض GameObjectManager ودالة LoadMap ، بالإضافة إلى الأحداث من مسار إنشاء GameObject.

لاستخدام حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لبرنامج Unity في مشروع Unity، يمكنك إضافة مكوِّن النص البرمجي لخدمة الخريطة إلى GameObject فارغ في المشهد. تضيف "خدمة الخرائط" تلقائيًا ميزة "GameObjects" التي تم إنشاؤها للخريطة على أنّها عناصر فرعية لهذا الارتساء GameObject. بعد إرفاق خدمة Maps (Script) بأداة GameObject الأساسية، يمكنك الوصول إلى سماتها العامة في Unity Inspector على النحو الموضّح هنا.

خدمة الخرائط (نص برمجي)

الميزات الجغرافية في لعبة Unity GameObjects

تعرض حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لبرنامج Unity الميزات الجغرافية (مثل المباني والطرق والمياه) من قاعدة بيانات "خرائط Google"، مثل Unity GameObjects في الألعاب. وفي وقت التشغيل، يتم إنشاؤها كعناصر ثانوية لـ GameObject الذي تم إرفاق المكوِّن MapsService به، وتكون لها أسماء على النحو التالي: {MapFeatureType} ({PlaceID}).

كائنات ألعاب حزمة تطوير البرامج (SDK)

إنشاء GameObject

أثناء اللعب، تُزيل حزمة تطوير البرامج (SDK) البيانات الجغرافية من قاعدة بيانات "خرائط Google" كمربّعات متجهات دلالية (عبر واجهة برمجة تطبيقات Semantic Tile API). فهو يفكّ ترميز هذه البيانات لحظيًا وتحويلها إلى Unity GameObjects. تتيح لك هذه الطريقة الوصول إلى بيانات ميزات الخريطة (كلّ من البيانات الوصفية والبيانات الهندسية) في أقرب فرصة، لتتمكّن من تخصيص GameObjects قبل وصولها إلى نهاية المراحل.

أول ما تفعله حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لبرنامج Unity عندما تتلقّى بيانات المتّجهات، هي إنشاء كائن MapFeature منها.

في مرحلة متوسطة ضمن مسار التنفيذ، يتم تخصيص كائنات MapFeature. أي أنها تصبح أنواعًا محددة (على سبيل المثال، Google.Maps.Feature.ModeledStructure). تحتوي عناصر MapFeature المتخصّصة هذه على MapFeatureShape تفاصيل الهندسة ( ModeledVolume في حالة ModeledStructure). وتشمل هذه التفاصيل كلاً من البيانات الخاصة بميزة MapFeature (مثل الرؤوس والمثلثات)، والواجهات المشتركة للوصول إلى الحقول المشتركة (مثل المربعات المحيطة).

يتم تحويل بيانات الهندسة إلى Unity Mesh، وإضافتها إلى GameObject الناتج من خلال MeshFilter، ثم يتم عرضها مع MeshRenderer.

الوصول إلى المسار

تظهر لك MapFeature من خلال الأحداث التي يتم بدؤها خلال مراحل مختلفة من مسار العملية. وتشمل هذه الأحداث أحداث WillCreate التي يتم تنشيطها قبل إنشاء GameObject مباشرةً، ما يسمح لك بتحديد خيارات التصميم أو حتى إلغاء الإنشاء، وأحداث DidCreate التي يتم تنشيطها بعد إنشاء GameObject مباشرةً، ما يتيح لك إجراء إضافات أو تغييرات على الشبكة النهائية.

كمثال، يمكنك فحص ExtrudedStructures بعد اندلاع حريق في WillCreateExtrudedStructureEvent وإخفاء جميع المباني التي يقل طولها عن 20 مترًا (أو يمكنك تخطي إنشائها تمامًا).

أنواع الأحداث

تحتوي مساحة الاسم Google.Maps.Event على فئة أحداث لكل نوع من أنواع الميزات الجغرافية.

يحتوي كل نوع من أنواع الأحداث هذه على عنصر حدث WillCreate وDidCreate عام يمكنك الاشتراك فيه، كما هو موضّح في مثال الرمز التالي.

dynamicMapsService.MapsService.Events.ExtrudedStructureEvents.DidCreate.AddListener(args => {

    // Apply nine-sliced walls and roof materials to this building.
    buildingTexturer.AssignNineSlicedMaterials(args.GameObject);

    // Add a border around the building base using the Building Border Builder class,
    // coloring it using the given border Material.
    Extruder.AddBuildingBorder(args.GameObject, args.MapFeature.Shape, BuildingAndRoadBorder);
});

فعاليات WillCreate

يتم تنشيط أحداث WillCreate مباشرةً بعد إنشاء MapFeature، ولكن قبل إنشاء GameObject النهائي منه. تتيح لك أحداث WillCreate إيقاف أو تخصيص عناصر GameObject التي تم إنشاؤها من MapFeature. تكون وسيطات الحدث WillCreate على النحو التالي:

using System.ComponentModel;
using Google.Maps.Decoded;
using UnityEngine;

namespace Google.Maps {
  public class WillCreateGameObjectEventArgs<T, U>
      : CancelEventArgs where T : IMapObject, U : IGameObjectStyle {

    public readonly T MapObject;
    public U Style;
    public GameObject Prefab;

    Public WillCreateGameObjectEventArgs(T mapObject, U defaultStyle, GameObject prefab) {
      MapObject = mapObject;
      Style = defaultStyle;
      Prefab = prefab;
    }
  }
}
  • يؤدي ضبط القيمة Cancel (المكتسَبة من CancelEventArgs) على صحيح إلى إيقاف إنشاء GameObject.
  • MapObject للقراءة فقط.
  • يتيح لك الإعداد Style تخصيص مظهر GameObject الذي تم إنشاؤه.
  • يؤدي الإعداد Prefab إلى استبدال GameObject الذي سيتم إنشاؤه بالعنصر المُسبَق.

فعاليات DidCreate

يتم تنشيط أحداث DidCreate بعد إنشاء GameObject، بعد إضافته إلى المشهد. وترسل إليك إشعارات عندما تم إنشاء GameObject بنجاح، ما يتيح لك إجراء المزيد من المعالجة. تكون وسيطات أحداث DidCreate على النحو التالي:

using System.ComponentModel;
using Google.Maps.Decoded;
using UnityEngine;

namespace Google.Maps {
  public class DidCreateGameObjectEventArgs<T, U>
      : EventArgs where T : IMapObject, U : IGameObjectStyle {

    public readonly T MapObject;
    public GameObject CreatedObject;

    Public DidCreateGameObjectEventArgs(T mapObject, GameObject createdObject) {
      MapObject = mapObject;
      CreatedObject = createdObject;
    }
  }
}
  • MapObject للقراءة فقط - ولذلك لن يؤدي تغييره إلى أي تغيير في المشهد.
  • سيؤدي تغيير السمة CreatedObject إلى تغيير GameObject الذي تمت إضافته إلى المشهد.

المباني

هناك نوعان من المباني: المباني المنبثقة والهياكل النموذجية.

المباني الناتجة عن البث المباشر

يتم إنشاء المباني المستخرجة من مخطط تفصيلي (أي بصمة ثنائية الأبعاد) وارتفاع. تمثل حزمة SDK معظم المباني بهذه الطريقة، ويتم إنشاؤها بالطرق الثلاث التالية:

  • استخدام بيانات الارتفاع في العالم الحقيقي (عند توفّر هذه المعلومات) وهذا هو السلوك التلقائي.

  • من خلال توفير ارتفاع ثابت لكل المباني، مع تجاهل ارتفاعها في الواقع.

  • من خلال توفير ارتفاع احتياطي لجميع المباني التي ليس لها ارتفاع حقيقي (يتم ضبط هذه القيمة تلقائيًا على 10 أمتار).

إنّ الجمع بين هذه الطرق الثلاث يسمح لحزمة Maps SDK for Unity بإنشاء مناظر مدينة بتباين واقعي يعكس العالم الحقيقي، أو بارتفاع ثابت للمبنى، أو مزيج من الاثنين.

الهياكل المستندة إلى نموذج

يتم إنشاء البنى المستندة إلى نموذج باستخدام المنهج العادي لتصميم النماذج الثلاثية الأبعاد للمثلثات المزيّنة بالفسيفساء. ويتم استخدام هذا النهج عادةً للمباني التاريخية، مثل تمثال الحرية.

تمثال الحرية النموذجي

تطبيق المواد

في Unity، تستخدم عملية العرض أدوات تظليل ومواد وزخارف لإضافة واقعية إلى GameObjects. تحدد الظلال كيفية تطبيق الزخارف والألوان والإضاءة على الأشكال الهندسية المعروضة، مع تخزين الزخارف والألوان والإعدادات الأخرى المستخدمة كمادة كمادة. وتستخدم مواد لتحديد كيفية عرض السطح - من خلال تضمين إشارات إلى الزخارف التي يستخدمها وإلى معلومات التجانب واللون.

وحدات التظليل هي نصوص صغيرة تحتوي على منطق احتساب لون كل بكسل، بناءً على مدخلات الإضاءة وعلى إعدادات المواد. تأتي حزمة تطوير البرامج (SDK) لـ "خرائط Google" لبرنامج Unity مع أداة تظليل عادية للبُنى النموذجية وأخرى لميزات الخريطة الأساسية، ولكنّها تدعم أيضًا تطبيق المواد المتقدّمة. يتم حساب إحداثيات الخرائط الخاصة بالأشعة فوق البنفسجية لميزة GameObjects على الخريطة بطريقة تتيح تطبيق أي مواد أساسية، وستبدو معقولة بدون تعديل.

للحصول على تأثيرات مادية أكثر تقدّمًا، توفِّر حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لبرنامج Unity بيانات إضافية لكل رأس من خلال قنوات UV إضافية، بالإضافة إلى عدد من الوظائف المناسبة لبرامج تظليل cg من خلال مكتبة GoogleMapsShaderLib. يتيح ذلك إجراء أشياء مثل زخارف بناء تسع شرائح، مثل قص زخرفة على السقف والأرض والحوائط والجدران المبلّطة، في مبنى.

لمزيد من المعلومات، يُرجى الاطّلاع على إنشاء المواد واستخدامها في دليل مستخدم Unity.

قنوات الأشعة فوق البنفسجية

تحتوي قنوات الأشعة فوق البنفسجية لكل نوع MapFeature على بيانات بالنموذج التالي:

ExtrudedStructure

Walls

يتم تشييد كل جدار على ExtrudedStructure كربعة من الأشكال التالية:

Walls

يتم حساب إحداثيات الأشعة فوق البنفسجية للجدران لكل رباعي. لا تتم مشاركة الرؤوس بين الكوات - للسماح بالعناصر الطبيعية الصلبة بين الجدران (أي السماح بأن تظهر زوايا الجدران كزوايا صلبة، بدلاً من حواف مستديرة ناعمة).

القناة 0: (س، ص، العرض، الارتفاع)
x وy هما الإحداثيات المتعلقة بالزاوية السفلية اليسرى لهذا المربّع (القسم المربع) من الجدار، في حين أنّ العرض والارتفاع هما عرض وارتفاع هذا اللوحة الرباعية للجدار. ينطبق ذلك على كل قاعدة تشكل الجدار.
سطح بناية

يمكن محاذاة زخارف السقف إما مع محور أو محاذاتها مع اتجاه ExtrudedStructure. يمكنك ضبط ذلك من خلال كائن ExtrudedStructureStyle.

القناة 0: (س، ص، العرض، الارتفاع)
x وy هما إحداثي كل رأس بالنسبة إلى الزاوية السفلية اليسرى من السقف (على وجه التحديد، زاوية مربّع تحديد السطح المنسّق مع محور الغطاء الأدنى). width وheight يحدّدان حجم مربّع حدود السقف.

Region

القناة 0: (س، ص، العرض، الارتفاع)
x وy هما إحداثيات كل رأس بالنسبة إلى أسفل الجانب الأيسر لمربّع تحديد المحور الذي تتم محاذاته مع المنطقة. ويحدّد كل من العرض والارتفاع حجم مربّع الحدود.

Segment

القناة 0: (س، ص، العرض، الطول)
x وx هما إحداثيات كل رأس، ويتم احتسابه كما لو كان الجزء مستقيمًا تمامًا للسماح بالانحناء حول الزوايا. يحدد x وx أبعاد الجزء.

ModeledStructure

القناة 0:
يتم ضبط كل إحداثي على (0، 0، 0، 0) لأنّه لا يتوفّر حاليًا أي تنفيذ لإحداثيات النسيج.

GoogleMapsShaderLib

تتضمن حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لبرنامج Unity مكتبة تظليل تُسمى GoogleMapsShaderLib، لمساعدتك في إنشاء برامج تظليل تعمل بشكلٍ جيد مع ميزة MapFeature GameObjects. تم تنفيذ المكتبة في ملف GoogleMapsShaderLib.cginc. يمكنك استخدام المكتبة من خلال تضمين توجيه #include التالي في قسم علامات CGPROGRAM في النص البرمجي لنافذة التظليل.

CGPROGRAM
// ...
#include "/Assets/GoogleMaps/Materials/GoogleMapsShaderLib.cginc"
// ...
ENDCG

تكون مكتبة التظليل مضمَّنة في GoogleMaps.unitypackage. بعد استيراد الحزمة، يمكنك العثور على GoogleMapsShaderLib.cginc داخل مجلد المشروع /Assets/GoogleMaps/Materials/.

تسعة شرائح

يتضمن GoogleMapsShaderLib وظيفة ملائمة يمكنك استخدامها في أدوات تظليل الأجزاء لتوفير تسعة شرائح من الزخارف. التقطيع إلى تسعة أجزاء هي تقنية لتغطية الأسطح بزخرفة، حيث يتم تقسيم الهيئة إلى تسعة أجزاء باستخدام سلسلة من الحدود. يتم تجانب المناطق الواقعة بين الحدود، فيما تظل المناطق خارج الحدود ثابتة - كما هو موضح هنا:

تسعة شرائح

على سبيل المثال، عند تطبيق زخرفة من تسع شرائح على جدار مبنى، يتم تطبيق الجزء العلوي من الزخرفة على الجزء العلوي من الجدار (تحت السقف مباشرةً)، ويتم تطبيق الجزء السفلي من الزخرفة على الجزء السفلي من الجدار (المتصلة بالأرض)، ويتم تطبيق جوانب الهيئة على حواف الجدار، ويتم تطبيق أجزاء الجزء العلوي من الزخرفة على حواف الجدار بشكل متساوٍ.

على الطرق (كمثال آخر)، تتيح لك المقاطع التسعة الحصول على رصيف بعرض ثابت، ولكن بعدد متغير من الممرات، اعتمادًا على عرض الطريق.

يمكنك استخدام تسعة شرائح عن طريق تضمين GoogleMapsShaderLib.cginc في التظليل، ثم استدعاء الدالة nineSlice. يتم تضمين نماذج لعوامل التظليل والمواد في GoogleMaps.unitypackage لتوضيح كيفية استخدام الدالة nineSlice لإنشاء ناطحة سحاب واقعية ذات أحجام متغيرة دون الحاجة إلى تمدُّد أو تمزيق.

مثال على موقع المواد
/Assets/GoogleMaps/Examples/04_Advanced/MoreStyling/Materials/NineSlicing
مثال على موقع Shader
/Assets/GoogleMaps/Examples/04_Advanced/MoreStyling/Materials/NineSlicing/BuildingWall.shader

يمكنك استخدام تسعة شرائح على أي MapFeature، باستثناء ModeledStructures، التي لا تحتوي حاليًا على أي إحداثيات زخرفية.

النظام الإحداثي

تستخدم حزمة تطوير البرامج (SDK) لـ "خرائط Google" لنظام الإحداثيات في Unity إسقاط Web Mercator للتحويل بين خطوط الطول والعرض الكروي WGS 84 وخط الطول والعرض الديكارتي (Vector3).

ترتبط قيم المتجه 3 بالأصل العائم، والذي يتم تعيينه عادةً على موقع البداية للمستخدم. ونتيجةً لذلك، يجب عدم الاحتفاظ بقيم Vector3 خارج الجلسة (أي على الخادم أو على جهاز المستخدم). ننصحك بتحديد المواقع الجغرافية الفعلية في العالم باستخدام أزواج من خطوط الطول والعرض.

يتم استخدام مصدر عائم لتجنُّب مشاكل ثبات النقطة العائمة. تستخدم فئة Vector3 في Unity أرقام النقاط العائمة أحادية الدقة وتنخفض كثافة أرقام النقاط العائمة القابلة للتمثيل مع زيادة المقدار (أي تصبح أرقام النقاط العائمة الأكبر أقل دقة). يمكنك تعديل الأصل العائم كلما ابتعد المستخدمون بعيدًا بما فيه الكفاية عن المصدر الذي سيتحوّل إلى مشكلة. يمكنك ضبطها على قيمة صغيرة نسبيًا (على سبيل المثال، 100 أو 200 متر)، أو أكبر (أكبر من 1 كيلومتر) استنادًا إلى عدد المرات التي تريد فيها إجراء التحديث.

يتم تعديل حجم Unity Worldspace إلى مقياس 1:1 (متر)، استنادًا إلى خط عرض المنشأ الأولي. في إسقاط ماركاتور، يختلف المقياس قليلاً باختلاف خط العرض، ولذلك يختلف مقياس Unity Wordspace بشكل طفيف عن 1:1 عندما يتحرك المستخدمون إلى الشمال والجنوب ومع ذلك، ليس من المتوقع أن يتحرك المستخدمون بعيدًا (أو بسرعة) بما يكفي لملاحظة ذلك.

تحتوي حزمة تطوير البرامج (SDK) لـ "خرائط Google" لبرنامج Unity على دوال إحالات ناجحة للإحالات الناجحة بين Google.Maps.LatLng وUnity Worldspace (Vector3) – التي تأخذ في الاعتبار الأصل العائم والمقياس.

تحميل الأخطاء

يمكن التعامل مع الأخطاء التي تحدث أثناء تحميل بيانات الخريطة من الشبكة من خلال حدث MapLoadErrorEvent. تعالج حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Unity معظم أنواع الأخطاء نفسها إذا لم تُضِف معالج أحداث. ومع ذلك، هناك خطأ يتطلب أن يتخذ تطبيقك بعض الإجراءات. يتم تحديد ذلك من خلال MapLoadErrorArgs.DetailedErrorCode وعلى النحو الموضّح أدناه.

UnsupportedClientVersion

لم يعُد هذا الإصدار من حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لبرنامج Unity متوافقًا، وربما كان ذلك إلى جانب مفتاح واجهة برمجة التطبيقات الحالي. يجب أن يطلب تطبيقك عادةً من المستخدم التحديث إلى إصدار أحدث من تطبيقك.

يعني هذا الخطأ عادةً أن إصدار حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل Unity قديم جدًا. في حالات نادرة، قد نستخدم هذا إذا اكتشفنا مشكلة خطيرة في إصدار SDK للخرائط من أجل Unity أو في مفتاح واجهة برمجة تطبيقات. سنبذل قصارى جهدنا لإبلاغ هذا الأمر وضمان عدم حدوث ذلك حتى يتوفر إصدار عملي من التطبيق متاح للتحديث.

من أفضل الممارسات التأكّد من توفّر مسار ترقية مناسب لتطبيقك في حال حدوث هذا الخطأ، ما يسمح للمستخدمين بالانتقال إلى إصدار أحدث من تطبيقك باستخدام إصدار متوافق من حزمة تطوير البرامج (SDK). لمزيد من المعلومات، راجِع مستندات مفتاح التبديل لإيقاف العميل.

المشاكل المعروفة

يتم عرض ميزات الخريطة الأساسية من الأمام إلى الأمام بدون اختبار z لأن جميع الميزات من هذا النوع يتم عرضها في المستوى نفسه. يجب ضبط اختبار z على ZTest Always على أي مواد بديلة تطبّقها على ميزات الخريطة الأساسية لضمان عرضها بشكل صحيح.

ضمّنت Google أداة تظليل النماذج التي تعالج هذه المشاكل في GoogleMaps.unitypackage. اسمه "BaseMapTextured.shader، ويوجد في المجلد /Assets/GoogleMaps/Materials/. لاستخدامه على مادة، اختَر Google > الخرائط > Shaders > Basemap Textured من قائمة "أداة التظليل" المنسدلة في "أداة فحص المواد".

عند تصميم عنصر Feature.Region أو Feature.AreaWater، يمكنك إضافة تعبئة باستخدام مادة أو لون مخصّص أو لون يتم إنشاؤه تلقائيًا ويتم اختياره من خلال تعداد FillModeType ضمن عنصر التصميم. Auto يتم إنشاء الألوان استنادًا إلى قيمة نوع استخدام "المنطقة".